GitHub Action中TSC构建报错但本地编译正常的排查问询

安全阿岳

2026-8-2

问题

使用act工具通过Docker本地测试GitHub Action工作流时，出现多种TypeScript错误（TS2345、TS18046、TS2339等），但本地开发及执行tsc -p tsconfig.build.json编译均正常。
已确认以下信息完全一致：

GitHub Action运行环境为ubuntu-latest，本地act使用的Docker容器与该环境的Node（v18.13.0）、npm（v8.19.3）、yarn（1.22.19）、tsc（v4.9.4）版本
通过tsc --showConfig输出对比，TSC使用的配置
直接进入GitHub Action使用的Docker容器执行相同编译命令无报错

附项目tsconfig.json配置：

{
  "compilerOptions": {
    "rootDir": "./src",
    "module": "commonjs",
    "declaration": false,
    "noImplicitAny": false,
    "skipLibCheck": true,
    "removeComments": true,
    "noLib": false,
    "allowSyntheticDefaultImports": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "target": "ES2021",
    "sourceMap": true,
    "outDir": "./dist",
    "baseUrl": "src",
    "incremental": true,
    "strictNullChecks": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "**/*.spec.ts"],
  "paths": {
    "@module": ["src/module"]
  }
}

可能的原因

act的工作目录映射问题：act挂载本地目录到容器时，可能存在路径大小写敏感差异（Linux容器对路径大小写敏感，本地如果是macOS/Windows可能不敏感），或者挂载了未忽略的增量编译缓存文件（比如.tsbuildinfo）。尝试删除本地.tsbuildinfo和dist目录后再用act测试，同时检查代码中导入路径的大小写是否和实际文件一致。
act的环境变量差异：尽管核心工具版本一致，act可能默认设置额外环境变量，或缺少本地的某些环境变量，导致TypeScript解析逻辑变化。可以在act执行的工作流中添加步骤打印所有环境变量，和本地环境对比，重点关注NODE_ENV、TS_NODE_PROJECT这类可能影响TS编译的变量。
依赖安装的差异：本地可能有缓存的依赖，而act容器中安装依赖时可能存在细微差异（比如yarn.lock/package-lock.json的版本锁定问题，或某些依赖的平台特定构建产物不同）。尝试在act的工作流中先删除node_modules和锁文件，重新安装依赖后再执行编译。
act的容器用户权限问题：act默认可能用root用户运行容器，而本地开发用普通用户，导致文件权限不同，TypeScript无法正确读取某些文件（比如类型定义文件）。可以在act命令中指定--user $(id -u):$(id -g)模拟本地用户权限测试。
tsconfig路径映射的解析问题：你的tsconfig中配置了paths映射，act容器中可能因为baseUrl的相对路径解析问题（比如容器内的工作目录和本地不同），导致路径映射不生效。可以在act的编译步骤中添加tsc --noEmit并指定绝对路径的tsconfig，或者检查容器内的工作目录是否和本地一致。
act的日志输出误导：某些情况下，act可能捕获到工作流中其他步骤的错误，误显示为TS编译错误。仔细查看错误的具体位置和上下文，确认是否是真正的编译错误，还是其他步骤的输出干扰。

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