Vercel部署Node API遇TypeORM错误：找不到Entity元数据

核心原因 #

这个错误基本和ORM的元数据加载逻辑相关，本地正常但Vercel异常，排除.env内容问题（拉取后本地可运行），问题大概率出在部署环境的文件结构、编译流程或环境变量加载时机上。

具体排查方向与解决方法 #

• ORM实体文件未被打包进部署产物
  Vercel的构建流程可能默认跳过了实体文件的编译或打包。检查你的构建脚本，确保实体文件（比如.ts）被编译到输出目录，同时ORM配置中的entities路径要指向编译后的文件（例如用dist/entities/**/*.js替代src/entities/**/*.ts）。
• 环境变量加载晚于ORM初始化
  Vercel的Serverless函数环境中，环境变量可能在ORM初始化之后才完成注入。要保证ORM初始化逻辑在环境变量完全加载后执行：比如把ORM初始化放在API路由的入口处，或者用dotenv.config()提前加载（Vercel会自动注入环境变量，但要避免异步加载导致的时序差）。
• Vercel Serverless函数的文件结构限制
  Vercel要求Serverless函数入口在api目录下，依赖模块的路径必须正确。如果实体文件不在API路由的依赖链里，会被打包工具剔除。可以在API入口文件中显式导入实体文件，或者调整vercel.json的functions配置，确保实体文件被包含进部署包。
• ORM缓存问题
  本地开发时ORM会生成元数据缓存，但Vercel部署环境是全新的，缓存无法复用且可能生成失败。建议关闭ORM的缓存功能（比如TypeORM设置cache: false），因为Vercel的Serverless环境是只读的，缓存目录无法写入。

额外验证步骤 #

• 查看Vercel部署日志，搜索是否有实体文件相关的警告或错误，比如“未找到实体文件”的提示。
• 手动触发Vercel重新部署，勾选「清空构建缓存」选项，避免旧缓存干扰。

内容的提问来源于stack exchange，提问作者Victor Braga