はじめに
Node.js のpunycode モジュールは Unicode 文字列を ASCII 文字列にエンコード・デコードするためのライブラリで、主に国際化ドメイン名（IDN）の処理で使用されていました。例えば、日本.com のような日本語ドメインを xn--wgv71a119e.com のような ASCII 文字列へ変換する際に使用されます。
この punycode モジュールですが、Node.js v21 以降では次のような Deprecation が表示されるようになります。
(node:51500) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(Use `node --trace-deprecation ...` to show where the warning was created)
punycode モジュールは package.json の依存関係で使用されているため、現時点で直接的に解決することは難しく、ビルドや開発時に大量の警告が表示されて、標準出力のノイズやビルド時間の増加といった問題を引き起こします。
この記事では Node.js の特定の警告コードを指定して無視する方法を紹介します。
punycode 非推奨警告の背景
Node.js v21 以降、以下の理由で非推奨となりました。
- セキュリティとメンテナンスの懸念
- ユーザランド（
punycode.js）実装の追加 - Node.js コアの軽量化方針
多くの npm パッケージが内部的に punycode を使用しているため、開発者が直接制御できない状況で警告が表示されます。
避けるべき解決方法
全ての非推奨警告を無視する
{
"scripts": {
"build": "node --no-deprecation next build"
}
}
実行コマンドに対して、直接 --no-deprecation を渡してしまうと、全ての非推奨警告も無視されてしまうため、セキュリティやパフォーマンスに関わる重要な警告を見逃すリスクがあります。
推奨される解決方法
特定の警告コード（DEP0040）のみを無視する
Node.js では、各非推奨警告に特定のコードが割り当てられています。punycode の場合は DEP0040 です。
警告コードを無視する方法には次のようなメリットがあります。
- punycode 関連の警告（DEP0040）のみを無視できる
- 他の重要な非推奨警告は表示され続ける
- 開発・ビルド・カスタムスクリプト全てに対応できる
-
cross-envによるクロスプラットフォームに対応できる
実装手順
1. 現在の問題を確認
ビルド時にどのような警告が表示されているか確認する。
$ npm run build
(node:51500) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(node:51508) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(node:51502) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
2. scripts セクションの修正
次のように修正しておく。
{
"scripts": {
- "start": "cross-env SOCKET=true tsx ./scripts/next-remote-watch.ts ./data",
+ "start": "cross-env SOCKET=true NODE_OPTIONS=\"--no-warnings=DEP0040\" tsx ./scripts/next-remote-watch.ts ./data",
- "dev": "next dev",
+ "dev": "cross-env NODE_OPTIONS=\"--no-warnings=DEP0040\" next dev",
- "build": "next build && tsx ./scripts/generate-sitemap.ts",
+ "build": "cross-env NODE_OPTIONS=\"--no-warnings=DEP0040\" next build && cross-env NODE_OPTIONS=\"--no-warnings=DEP0040\" tsx ./scripts/generate-sitemap.ts"
}
}
3. cross-env の確認
cross-env が devDependencies に含まれていることを確認する。
{
"devDependencies": {
"cross-env": "^7.0.3"
}
}
インストールされていない場合は次のコマンドで追加する。
$ npm install --save-dev cross-env
4. 動作確認
$ npm run build
$ npm run dev
修正前後の比較
修正前の出力
> next build && tsx ./scripts/generate-sitemap.ts
▲ Next.js 15.5.3
(node:51500) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(node:51508) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(node:51502) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(node:51509) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(node:51505) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
✓ Linting and checking validity of types
Creating an optimized production build ...
✓ Compiled successfully in 4.8s
修正後の出力
> cross-env NODE_OPTIONS="--no-warnings=DEP0040" next build && cross-env NODE_OPTIONS="--no-warnings=DEP0040" tsx ./scripts/generate-sitemap.ts
▲ Next.js 15.5.3
✓ Linting and checking validity of types
Creating an optimized production build ...
✓ Compiled successfully in 1730ms
✓ Collecting page data
✓ Collecting build traces
✓ Finalizing page optimization
これで、punycode の警告が完全に消え、ビルド時間も改善（4.8s → 1.7s）しました。
他のビルドツールでの対応
Vite
{
"scripts": {
"build": "cross-env NODE_OPTIONS=\"--no-warnings=DEP0040\" vite build"
}
}
Webpack
{
"scripts": {
"build": "cross-env NODE_OPTIONS=\"--no-warnings=DEP0040\" webpack --mode production"
}
}
CI（GitHub Actions）
- name: Build
run: npm run build
env:
NODE_OPTIONS: "--no-warnings=DEP0040"
【代替案】package.json での根本解決
{
"overrides": {
"punycode": "npm:punycode.js@^2.3.1"
},
"resolutions": {
"punycode": "npm:punycode.js@^2.3.1",
"**/punycode": "npm:punycode.js@^2.3.1"
}
}
根本的な解決方法として punycode の代替ライブラリを明示的に指定する方法もありますが、次の観点で推奨されません。
- 依存関係の解決に影響を与える可能性
- 予期しない互換性問題が発生する可能性
- 警告の無視の方が安全で確実
まとめ
punycode 非推奨警告への対応方法
推奨アプローチ
-
--no-warnings=DEP0040で特定警告のみを無視 -
cross-envでクロスプラットフォーム対応 - 開発・ビルド・カスタムスクリプト全てに適用
- 他の重要な警告は引き続き表示
避けるべきアプローチ
-
--no-deprecationで全警告を無視 - 依存関係の強制的な変更
特定のコードで弾いておけば、Node.js のアップデートに伴う一時的な移行期間の問題を適切に処理することができ、セキュリティやパフォーマンスに関わる重要な情報を見逃すリスクも最小限に抑えられます。