Angular 17 SSR添加class-transformer@Type装饰器后报错Reflect.getMetadata is not a function

核心原因 #

Angular 17的SSR（尤其是基于Vite的构建链）默认未全局注入reflect-metadata，且传统polyfills.ts在SSR环境下可能无法正确加载，导致服务端渲染阶段缺失该API。

具体解决步骤 #

1. 确认依赖安装 #

先确保reflect-metadata已正确安装：

npm install reflect-metadata

2. 在服务端入口文件顶部导入reflect-metadata #

Angular 17的SSR服务端入口为server.ts，将导入语句放在文件最开头，确保全局环境优先初始化该API：

import 'reflect-metadata';
// 其他导入语句放在后面

3. 配置Vite适配SSR（Vite构建链适用） #

在vite.config.ts中添加SSR相关配置，确保reflect-metadata和class-transformer被正确打包进服务端代码：

import { defineConfig } from 'vite';
import angular from '@angular-devkit/build-angular/src/tools/browser/vite/index.mjs';

export default defineConfig({
  plugins: [angular()],
  ssr: {
    noExternal: ['class-transformer', 'reflect-metadata'],
    optimizeDeps: {
      include: ['reflect-metadata']
    }
  }
});

4. 规范class-transformer的使用方式 #

建议将@Type装饰器用于独立的DTO类而非组件类（组件类使用虽可行，但DTO类更符合数据转换的设计场景）：

import { Type } from 'class-transformer';

export class DataModel {
  @Type(() => Date)
  date: Date;
}

之后在组件中引入并使用该DTO类即可。

5. 重启SSR服务 #

修改配置后完全停止当前服务，重新启动生效：

npm run dev:ssr

额外排查点 #

• 若使用Webpack构建的Angular 17项目，需在webpack.server.config.js中配置全局导入reflect-metadata，或同样在server.ts顶部导入。
• 检查是否有其他第三方库覆盖了Reflect对象，导致getMetadata方法丢失。

内容的提问来源于stack exchange，提问作者Renat Gubaev