Vercel部署Node+Express+TypeScript API时持续出现404 Not Found问题

针对你遇到的部署后持续返回404的情况，从以下核心维度排查：

1. 补全TypeScript编译配置 #

你未提供tsconfig.json，但这是生成正确dist文件的关键：

• 必须设置outDir: "./dist"，确保编译产物输出到指定目录
• 配置rootDir: "./src"，明确源码根目录
• include数组需包含"src/**/*"，保证所有源码文件被编译

参考配置示例：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

本地先执行npm run build，确认dist目录下生成了index.js且代码为最新编译结果。

2. 修正vercel.json配置 #

当前路径匹配逻辑可能存在问题，提供两种调整方案：

方案一：直接使用源码入口（推荐，Vercel自动处理编译） #

{
  "version": 2,
  "builds": [
    {
      "src": "src/index.ts",
      "use": "@vercel/node",
      "config": {
        "runtime": "nodejs18.x",
        "buildCommand": "npm run build"
      }
    }
  ],
  "routes": [
    {
      "src": "/(.*)",
      "dest": "/src/index.ts"
    }
  ]
}

方案二：使用dist编译产物作为入口 #

若坚持用编译后的文件，确保路径完全匹配：

{
  "version": 2,
  "builds": [
    {
      "src": "dist/index.js",
      "use": "@vercel/node"
    }
  ],
  "routes": [
    {
      "src": "/.*",
      "dest": "dist/index.js"
    }
  ]
}

3. 调整package.json关键配置 #

• 将main字段修改为"dist/index.js"，Vercel会读取该字段作为项目入口
• 确认build命令tsc能正常执行，本地验证编译流程无报错
• 保证本地Node版本与engines中指定的18.x一致，避免编译环境差异

4. 检查Express代码路由逻辑 #

• 404处理中间件必须放在所有业务路由之后定义，避免提前拦截请求
• 不要使用app.listen()启动服务，Vercel会自动处理端口监听，直接导出app即可：

import express from 'express';
const app = express();

// 先定义所有业务路由
app.get('/api/test', (req, res) => {
  res.json({ data: 'success' });
});

// 最后定义404处理
app.use((req, res) => {
  res.status(404).json({ message: 'Not Found' });
});

// 导出app供Vercel使用
export default app;

5. 查看Vercel部署日志 #

进入Vercel控制台的部署详情页，检查Build和Output日志：

• 确认npm run build无编译错误，dist目录正常生成
• 排查是否存在路径相关的警告或错误提示
• 验证部署产物中包含dist（或src）文件夹

6. 清除缓存重新部署 #

旧缓存可能导致配置不生效，在Vercel部署页点击「重新部署」，选择「清除构建缓存并重新部署」

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