部署后Swagger无法显示接口文档（Typescript环境）

云上老周

2026-7-2

问题分析与解决

核心原因

你猜的没错，这确实和TS编译时的注释处理有关——TS默认编译会丢弃所有JSDoc注释，再加上你部署环境里通常只有编译后的.js文件，但Swagger配置里的apis指定的是["**/*.ts"]，部署时swagger-jsdocs找不到这些TS文件，自然没法生成接口文档。就算侥幸能找到TS文件，编译后的JS里没了注释，也会导致读取失败。

解决方案

1. 调整TS编译配置，保留注释

修改tsconfig.json，强制编译时保留JSDoc注释：

{
  "compilerOptions": {
    "removeComments": false, // 关键配置：设为false，禁止删除注释
    "outDir": "./dist", // 你的编译输出目录，按实际情况调整
    // 其他原有配置...
  }
}

2. 更新Swagger的API文件路径，指向编译后的JS

部署环境要读取编译好的.js文件，所以修改Swagger配置里的apis字段：

const options = {
  definition: {
    // 原有配置不变，记得把servers里的url改成部署环境的地址
    servers: [
      {
        url: "http://你的部署域名/端口",
        description: "Production Server"
      },
    ],
  },
  // 按你的编译输出目录调整，比如所有JS都在dist下就写["dist/**/*.js"]
  apis: ["dist/**/*.js"] 
};

3. 本地/部署环境适配（可选）

如果想本地开发用TS文件，部署用JS文件，可以通过环境变量区分：

const isProd = process.env.NODE_ENV === 'production';
const options = {
  definition: {
    // 原有配置...
    servers: [
      {
        url: isProd ? "http://部署地址" : "http://localhost:8080",
        description: isProd ? "Production Server" : "Local Server"
      },
    ],
  },
  apis: isProd ? ["dist/**/*.js"] : ["**/*.ts"]
};