Next.js TranspilePackages为何仍解析可选依赖并抛出错误？

我在Next.js项目中使用一个依赖mongoose的本地NPM包，已经在next.config.js中配置了transpilePackages: ['my-package']来编译该包。Mongoose的部分可选功能依赖supports-color、kerberos等包，但我并未使用这些功能，本不需要安装这些依赖，可Next.js还是抛出了以下错误：

warn  - ../my-package/node_modules/debug/src/node.js
Module not found: Can't resolve 'supports-color' in '/my-package/node_modules/debug/src'

Import trace for requested module:
../my-package/node_modules/debug/src/node.js
../my-package/node_modules/debug/src/index.js
../my-package/node_modules/mquery/lib/mquery.js
../my-package/node_modules/mongoose/lib/index.js
../my-package/node_modules/mongoose/index.js

../my-package/node_modules/mongodb/lib/deps.js
Module not found: Can't resolve 'kerberos' in '/my-package/node_modules/mongodb/lib'

Import trace for requested module:
../my-package/node_modules/mongodb/lib/deps.js
../my-package/node_modules/mongodb/lib/index.js
../my-package/node_modules/mongoose/lib/index.js
../my-package/node_modules/mongoose/index.js

我预期不会出现此类错误，请问这是为什么？

原因分析 #

这些依赖虽然是Mongoose的可选功能依赖，但Next.js在转译本地包my-package时，会递归处理它的所有嵌套依赖（包括mongoose、mongodb、debug）。而这些依赖的代码中是同步导入了这些可选包的，Webpack在打包阶段会检查所有同步引入的模块是否存在——不管你实际有没有用到对应的功能，只要代码里写了require()或import，就会触发这个检查。

解决方案 #

方案1：安装可选依赖为开发依赖

最简单的解决方式是把这些缺失的包安装为devDependencies，因为它们只是打包阶段需要检查存在，运行时如果不用对应功能不会实际加载：

npm install supports-color kerberos --save-dev
# 或使用yarn
yarn add supports-color kerberos -D

方案2：配置Webpack忽略缺失的可选依赖

如果你不想安装多余依赖，可以修改next.config.js，告诉Webpack这些缺失的模块直接忽略，不进行解析：

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['my-package'],
  webpack: (config) => {
    config.resolve.fallback = {
      ...config.resolve.fallback,
      // 忽略可选依赖的解析
      'supports-color': false,
      'kerberos': false
    };
    return config;
  },
};

module.exports = nextConfig;

⚠️ 注意：必须确保你完全不会用到依赖这些包的功能（比如Kerberos认证、带颜色的调试日志），否则运行时会报错。

方案3：在本地包中声明依赖（若你维护该包）

如果my-package是你自己开发的，可以在它的package.json中把这些可选依赖添加到devDependencies，或者声明为peerDependencies，让使用该包的项目自行决定是否安装，从根源上避免主项目的打包问题。

内容的提问来源于stack exchange，提问作者Same Vision