本地file依赖在GitHub Actions中触发TypeScript模块找不到错误

问题场景 #

本地项目包含/foo和/bar两个独立包目录，各自有package.json。在/bar的package.json中通过以下方式引入/foo作为本地依赖：

"dependencies": {
  "foo": "file:../foo"
}

该配置在本地运行正常，但在GitHub Actions中执行时，TypeScript报错：

Cannot find module 'foo' or its corresponding type declarations.

解决步骤 #

1. 确保工作流的目录上下文正确 #

GitHub Actions默认以仓库根目录为工作目录，若/bar是子目录，需先切换到对应目录执行依赖安装，保证file:../foo的相对路径能正确指向/foo。示例工作流步骤：

- name: Install bar dependencies
  working-directory: ./bar
  run: npm install

2. 先构建/foo并生成类型声明 #

本地环境可能已提前构建过/foo，但GitHub Actions是全新环境，需先完成/foo的构建，确保类型声明文件（.d.ts）存在：

1. 在/foo的package.json中配置types字段，指定类型文件路径：

   "types": "./dist/index.d.ts"
   

2. 在工作流中先构建/foo，再安装/bar的依赖：

   - name: Build foo package
     working-directory: ./foo
     run: |
       npm install
       npm run build
   - name: Install bar dependencies
     working-directory: ./bar
     run: npm install
   

3. 配置TypeScript路径映射 #

若/foo未发布到npm，TypeScript可能无法自动识别本地依赖的类型，可在/bar的tsconfig.json中添加路径映射：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "foo": ["../foo/src"] // 或指向foo的类型声明文件所在路径
    }
  }
}

若使用此配置，构建时需用tsc-alias替换路径别名，避免生产环境路径异常：

npm install -D tsc-alias

然后在/bar的package.json中更新构建脚本：

"scripts": {
  "build": "tsc && tsc-alias"
}

4. 清理依赖缓存 #

GitHub Actions的依赖缓存可能导致本地依赖未正确更新，可在安装时禁用缓存：

- name: Install bar dependencies
  working-directory: ./bar
  run: npm install --no-cache

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