👁 59 次阅读

Next.js 构建后类名被压缩为何会让依赖类名的库失效

来源链接：https://github.com/vercel/next.js/issues/59594

现象描述

在 Next.js 14 应用中使用依赖类名反射的库时，构建后的生产环境会出现模型名被改成单字符的问题。issue #59594 给出的复现步骤显示：开发模式启动后浏览器和终端能正确显示模型名 BrokenModel；执行 npm run nx build next-broken 并以 npm run nx run next-broken:serve:production 启动生产模式后，模型名变成 p。报告者使用的环境为：Node 18.18.2、npm 9.8.1、pnpm 8.9.2、next 14.0.5-canary.10、react 18.2.0、typescript 5.2.2，操作系统为 Darwin Kernel Version 23.0.0（darwin/arm64）。报告者指出该问题从 Next.js 14 开始出现，在 "next": "13.4.19" 上工作正常。该问题同时被多位开发者以不同技术栈复现。issue 讨论中先后出现 Typegoose、sequelize-typescript、TypeORM、MikroORM 等库的受影响报告。issue 保持 open 状态，截至末条实质评论，官方尚未合入方案。

背景原因

issue 讨论中 @octet-stream 给出了定位线索：问题可能与提交 30da48fcd28b1fc07dcfa06d89b28bec95897d10 有关，该提交为服务端代码启用了压缩（minification）。该评论指出，服务端压缩目前由 SWC 处理，而 SWC 会破坏被装饰的类的类名。这一判断属于社区侧的分析，据 issue 讨论，官方未在评论中确认该归因。从实际现象看，Typegoose、sequelize-typescript、TypeORM、MikroORM 这类库在运行时需要通过类名或装饰器元数据推断模型名、表名与集合名。生产构建把类名压缩为短标识符（例如 p），库拿不到原始类名，就生成了错误的模型名或无法完成模型注入。不同用户给出的复现结论存在分歧：

@therk 表示在 Next 13.5.6 上也遇到同样问题，并指出 @octet-stream 曾通过 issue #58126 提出，但因不符合 bug 模板被关闭。
@octet-stream 说明该 issue 被关闭的原因是仓库可见性问题导致机器人无法确认复现链接。
@meronogbai、@logusgraphics 等确认 serverMinification 设为 false 后问题消失。
@logusgraphics 使用 swcMinify: false 并收到提示：「Disabling SWC Minifer will not be an option in the next major version. Please report any issues you may be experiencing to https://github.com/vercel/next.js」。

排查或量化方法

issue 中给出的验证路径，围绕「关掉服务端压缩后问题是否消失」展开： 1. 在开发模式下确认依赖类名的库能正常解析模型名（例如显示 BrokenModel）。 2. 执行生产构建并在生产模式启动，观察模型名是否被压缩为短标识符。 3. 在 next.config.js 中关闭压缩，重新构建并观察结果。报告者给出的配置片段为：

webpack: (config) => {
    config.optimization.minimize = false;
    return config;
  },

报告者说明，该方式下构建结果正常，但构建未做优化，对生产环境不可接受。报告者同时给出一个折中方式：使用 TerserPlugin 并设置 keep_classnames: true，据 issue 讨论该方式可以工作。issue 正文提及复现仓库中提供了 with-terser 分支。 issue 讨论中还出现另一条配置路径：@meronogbai 与 @logusgraphics 分别反馈 serverMinification 设为 false 有效。@kosiakMD 在 2025-02-07 的评论中表示 serverMinification: false 在折腾六小时后解决了问题。

完整解决方案（含必要代码）

官方侧尚未合入方案，以下均为 issue 讨论中社区成员给出的变通做法，按适用场景分类。针对 TypeORM 用户，@AleFons 在 2024-06-05 的评论中给出如下方案，并说明该方案在 serverMinification 开启的情况下也有效，且不依赖 EntitySchema。原始思路来自 typeorm/typeorm#4714 的评论： > Looping over getMetadataArgsStorage() and running Object.defineProperty() for each registered entity solved this for me. This works with serverMinification enabled and does not rely on EntitySchema. @ricklabanca 在 2025-04-10 的评论中引用了同一方案。针对 Typegoose 用户，@eroo36 在 2025-07-22 的评论中给出如下代码，思路是在 getModelForClass 时显式指定集合名：

const UserModel = getModelForClass(User, {
  schemaOptions: { collection: "users" }, // Specify the collection name because nextjs builds minifies the class names
});

据 issue 讨论，@RaschidJFR 在 2025-10-25 的评论中表示该方式在自己环境中不生效，直到关闭相关压缩后才恢复正常。同一份方案出现「可用」与「不可用」两种反馈，采用前需在自身项目中验证。针对 MikroORM 用户，@andres-dejesus 在 2024-07-30 的评论中列出尝试过但均无效的路径：

Adding types to property decorators
Using EntitySchema
Adding tablename to Entity decorator
Moving all entities to same config file

该用户进一步在 2025-12-19 的评论中表示，即便启用了 emitDecoratorMetadata，在 Nextjs 16.1.0 上配合 Turbopack 仍无法使用 MikroORM，并给出生产环境（Vercel）查询数据库时的报错原文： > If you are using decorators, ensure you have ’emitDecoratorMetadata’ enabled in your tsconfig.json. 该用户补充说明，使用 webpack 没有出现该问题。针对 Turbopack 场景，@hayksaryan 在 2025-10-23 的评论中表示 MikroORM 与 Turbopack 组合下同样存在该问题。使用 webpack 时至少可以手动关闭类名混淆，给出的配置片段为：

webpackConfig.optimization = {
        ...webpackConfig.optimization,
        minimizer: [
          new TerserPlugin({
            minify: TerserPlugin.swcMinify,
            terserOptions: {
              mangle: false,
            },
          }),
        ],

参数或对比表格

方案	提供者	适用场景	讨论中的反馈
`webpack` 配置中 `config.optimization.minimize = false`	报告者	通用，关闭构建压缩	构建正常但性能不优化，据 issue 讨论对生产不可接受
`swcMinify: false`	@logusgraphics	通用	有效，但收到未来主版本将移除该选项的提示
`serverMinification: false`	@meronogbai、@logusgraphics、@kosiakMD	关闭服务端压缩	多位用户反馈有效
`TerserPlugin` + `keep_classnames: true`	报告者	需要保留类名同时维持压缩	据 issue 讨论可以工作
遍历 `getMetadataArgsStorage()` + `Object.defineProperty()`	@AleFons	TypeORM	在 `serverMinification` 开启下有效，不依赖 `EntitySchema`
`getModelForClass` 指定 `schemaOptions.collection`	@eroo36	Typegoose	有用户反馈无效，需自行验证
`TerserPlugin` + `terserOptions.mangle: false`	@hayksaryan	webpack 下的 Turbopack 替代方案	用于手动关闭类名混淆

常见错误排查

模型名在生产构建后变成单字符（如 p）：确认依赖是否通过类名反射生成模型名，优先检查 serverMinification、swcMinify 相关配置。
swcMinify: false 生效但输出弃用警告：该提示来自 Next.js 构建过程，据 issue 讨论，社区对该方式的长期可用性存疑，需关注后续主版本。
TypeORM 场景下 EntitySchema、实体装饰器加表名等常见做法无效：@andres-dejesus 报告这些路径在其环境中均未解决问题，可参考遍历 getMetadataArgsStorage() 的方案。
MikroORM + Turbopack 下报 emitDecoratorMetadata 相关错误：@andres-dejesus 在 Nextjs 16.1.0 与 Vercel 生产环境报告该现象，并说明 webpack 下未出现，可考虑切换到 webpack 构建路径。
Typegoose 场景显式指定集合名仍不生效：@RaschidJFR 反馈该方式无效，建议结合 serverMinification: false 一并验证。

实践建议

优先判断依赖库是否属于「运行时依赖类名」这一类。Typegoose、sequelize-typescript、TypeORM、MikroORM 都在 issue 讨论中出现了受影响报告。对这类库，从 Next.js 13 升级到 14 后需要在类名保真与构建压缩之间做取舍。已确认可用的方式集中在三类：关闭服务端压缩（serverMinification: false、swcMinify: false）、保留类名（TerserPlugin 的 keep_classnames: true）、在应用层显式声明模型名或集合名。第三种方式对 TypeORM 与 Typegoose 有社区成员给出的具体代码，但反馈不一，需要在目标版本上实测。 Turbopack 路径下，社区给出的方案覆盖不足。@hayksaryan 与 @andres-dejesus 的报告均指向 MikroORM 与 Turbopack 组合下问题持续存在，其中一位在 Nextjs 16.1.0 上仍复现。使用该组合的项目，据 issue 讨论可继续使用 webpack 构建路径，或参考 terserOptions.mangle: false 的自定义 minimizer 配置。该 issue 当前状态为 open，官方尚未给出统一指引。issue 正文中的诉求「It would be nice to get an official guideline」在已有讨论中未见官方回应。

FAQ

Next.js 构建后类名被压缩为什么会导致模型名错误？ 依赖类名反射的库在运行时会读取类名来生成模型名、表名或集合名。生产构建把类名压缩成短标识符后，库读取到的名称与预期不符，Typegoose 等库因此生成错误的模型名。 这个问题从哪个版本开始出现？ 据 issue 正文，报告者在使用 "next": "13.4.19" 时正常，升级到 Next.js 14 后出现问题，并表示在 14.0.5-canary.10 上可复现。@therk 反馈在 Next 13.5.6 上也遇到同样问题，说明版本边界在讨论中并不完全一致。 关闭压缩能解决问题吗？ issue 讨论中多位用户反馈 serverMinification: false 有效，@kosiakMD 在折腾六小时后用该配置解决。报告者给出的 config.optimization.minimize = false 也能让构建结果正常，但会牺牲构建优化。 SWC 与类名压缩有什么关系？ @octet-stream 在讨论中指出，提交 30da48fcd28b1fc07dcfa06d89b28bec95897d10 为服务端代码启用了压缩，服务端压缩由 SWC 处理，该提交「seem to me that SWC breaks class names for decorated classes」。该归因属于社区分析，官方未在评论中确认。 issue 现在修好了吗？ 该 issue 保持 open，截至末条实质评论官方尚未合入方案。社区侧缓解方式集中在关闭服务端压缩、保留类名以及在应用层显式指定模型名或集合名三类，其中 TypeORM 与 Typegoose 场景有可参考代码，MikroORM 与 Turbopack 组合下仍有用户在更新版本上复现。