解决 Node.js 中 punycode 模块弃用警告

问题概述

当使用 Mongoose 连接 MongoDB 数据库时，Node.js 会抛出以下警告：

(node:22063) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. 
Please use a userland alternative instead.

该问题通常出现在 Node.js 18+ 环境中（包括 v18.18.0、v20.9.0、v21+等），主要特征包括：

• 警告来源于 Node.js 核心模块而非用户代码
• 可能通过 tr46 或 uri-js 等依赖引入
• 降级 Node.js 版本也无法彻底解决
• 在 Ubuntu/Windows/macOS 等多个平台均会出现

根本原因

1. Node.js 从 v21 开始将 punycode 核心模块标记为弃用状态
2. Mongoose 或其依赖链中的包（如 uri-js）仍在引用该弃用模块
3. 在 Node.js 20 后的版本中弃用警告默认开启

推荐解决方案

✅ 最佳方案：更新 uri-js 到最新版

npm install uri-js@4.2.2

验证方法：

1. 在 package-lock.json 中搜索 uri-js
2. 确认版本为 4.2.2 或更高
3. 重新启动应用

原理说明

新版 uri-js 移除了对 punycode 的依赖，此方法在 Node.js 18-22 版本均验证有效

✅ 升级 Node.js 到 LTS 版本

nvm install 22.14.0
nvm use 22.14.0

注意

确保相关依赖与新版本 Node.js 兼容：

npm outdated
npm update

✅ 彻底重新安装模块

# 清除缓存和依赖
rm -rf node_modules package-lock.json

# 重新安装
npm install

# 验证 mongoose 连接 (使用 Promise 语法)
const mongoose = require('mongoose');

mongoose.connect('mongodb://localhost:27017/mydb')
  .then(() => console.log('DB connected'))
  .catch(err => console.error(err));

临时解决方案

⚠ 抑制警告（开发环境专用）

# Linux/macOS
export NODE_OPTIONS="--no-deprecation"

# Windows PowerShell
$env:NODE_OPTIONS = "--no-deprecation"

或在代码中添加：

// 添加到入口文件顶部
process.on('warning', warning => {
  if (warning.code !== 'DEP0040') console.warn(warning);
});

注意

此方法会隐藏所有弃用警告，仅建议作为临时解决方案

不推荐的方法

❌ 修改 node_modules 内部文件

// 不推荐！修改 tr46/index.js
const punycode = require('punycode/');  // 添加斜杠

缺点：每次安装依赖都会被覆盖，可能引入兼容性问题

❌ 手动卸载 punycode

npm uninstall punycode  # 通常无效

原因：punycode 属于 Node.js 核心模块，不能被卸载

问题排查步骤

1. 确认警告来源

node --trace-deprecation your-app.js

2. 检查依赖树

npm ls punycode

3. 识别过时组件

npm outdated

总结建议

解决方案	推荐指数	适用场景
更新 uri-js	⭐⭐⭐⭐⭐	所有版本通用方案
升级 Node>=22.14	⭐⭐⭐⭐	可接受新版本的环境
重新安装模块	⭐⭐⭐	依赖混乱时使用
抑制警告	⭐⭐	紧急临时方案

最终建议：

1. 首选更新 uri-js 到 4.2.2+
2. 考虑升级到 Node.js 22.14+ LTS
3. 避免修改 node_modules 或卸载核心模块

遵循这些解决方案可彻底消除警告，同时确保应用遵循 Node.js 的长期支持策略。