GitHub Workflow执行tsc编译报错，本地无错的排查求助

两天前通过GitHub Workflow部署Node.js服务无任何错误，仅添加一个小型测试用例并升级版本后，今日触发的GitHub Workflow出现编译错误。

报错任务详情 #

tsc --noEmit --noErrorTruncation --pretty --resolveJsonModule -p tsconfig.json

Found 10 errors in 3 files.

Errors  Files
     1  src/routes/__test__/signout.test.ts:21
     1  src/routes/__test__/signup.test.ts:151
     8  src/routes/__test__/update.test.ts:94
Error: Process completed with exit code 2.

本地运行相同的npm run check命令无任何错误。

环境信息 #

• GitHub Workflow环境：

  node: v20.11.1 
  npm: 10.2.4
  yarn: 1.22.22
  

  （最初报错使用node v16，升级到v20后问题依旧）
• 本地WSL2环境：

  node: v20.11.1
  npm: 10.5.0
  

tsconfig.json配置 #

{
    "compilerOptions": {
        "target": "ES6" /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */,
        "module": "commonjs" /* Specify what module code is generated. */,
        "noEmit": true /* Disable emitting files from a compilation. */,
        "esModuleInterop": true /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */,
        "forceConsistentCasingInFileNames": true /* Ensure that casing is correct in imports. */,
        "strict": true /* Enable all strict type-checking options. */,
        "skipLibCheck": true /* Skip type checking all .d.ts files. */
    },
    "include": ["src", "global.d.ts", "src/**/*.ts", "src/**/*.tsx", "src/**/*.vue", "tests/**/*.ts", "tests/**/*.tsx"],
    "exclude": [
        "node_modules",
        "./node_modules",
        "./node_modules/*",
        "./node_modules/@types/node/index.d.ts",
        "node_modules/**",
        "plugins",
        "public"
    ]
}

异常点 #

测试用例中大量使用.set('Cookie', cookie)，但GitHub上的tsc编译仅报告10个错误，并非所有测试文件都报错。

可能原因 #

1. 依赖版本不一致：本地和GitHub环境的npm/yarn依赖安装结果不同，比如lock文件未提交，或者依赖包有跨版本的类型定义差异。虽然node版本一致，但npm版本不同（本地10.5.0 vs GitHub 10.2.4），可能导致依赖安装的细微差异。
2. 缓存问题：GitHub Workflow可能缓存了旧的依赖或编译产物，导致类型检查使用了过时的文件。
3. 文件大小写问题：WSL2默认对文件大小写不敏感，但GitHub的Linux runner是大小写敏感的，可能存在导入路径的大小写不匹配，仅在部分文件触发错误。
4. 测试用例的类型依赖差异：新增的测试用例可能引入了新的类型依赖，或者版本升级后，部分库的类型定义发生了变化，仅在特定测试场景触发类型错误。
5. tsconfig的include/exclude逻辑差异：本地和GitHub环境中，文件目录结构可能存在细微差异（比如是否存在某些自动生成的文件），导致tsc扫描的文件范围不同。

排查步骤 #

1. 同步依赖锁定文件：确保package-lock.json或yarn.lock已提交到仓库，GitHub Workflow使用相同的锁定文件安装依赖，避免版本不一致。
2. 清理GitHub缓存：在Workflow中添加步骤清理依赖缓存，比如使用actions/cache时设置动态key，或者直接跳过缓存重新执行npm install。
3. 检查文件大小写：检查报错文件及其导入的模块路径，确保大小写完全匹配，尤其是WSL2中编写的代码可能忽略了大小写规则。
4. 在本地模拟GitHub环境：
   • 安装npm 10.2.4，删除本地node_modules和package-lock.json，重新执行npm install和npm run check，看是否能复现错误。
   • 使用Docker模拟Linux环境，运行类型检查命令，验证环境差异导致的问题。
5. 查看完整错误信息：在GitHub Workflow的报错日志中，展开完整的tsc错误详情（当前仅显示错误数量和文件，未显示具体错误内容），根据具体提示定位问题。
6. 检查版本升级的影响：对比版本升级前后的依赖变化，查看是否有库的类型定义版本发生更新，尤其是和HTTP请求、Cookie相关的库（比如supertest、@types/supertest）。
7. 验证tsconfig的有效性：在GitHub环境中执行tsc --listFiles，查看tsc实际扫描的文件列表，和本地结果对比，确认是否存在文件范围差异。

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