如何解决AWS CodeBuild中NodeJS项目的TS2307编译错误？

问题 #

我搭建了一条将NodeJS（TypeScript）应用部署至AWS Elastic Beanstalk的流水线，但在CodeBuild的编译阶段遭遇TS2307错误。该项目在我的本地MacOS环境中构建完全正常。以下是错误输出以及我的buildspec.yml和tsconfig.json配置，恳请提供解决此AWS CodeBuild问题的思路。

错误输出 #

[Container] 2023/12/21 21:25:39.535669 Phase complete: PRE_BUILD State: SUCCEEDED
[Container] 2023/12/21 21:25:39.535686 Phase context status code:  Message: 
[Container] 2023/12/21 21:25:39.565655 Entering phase BUILD
[Container] 2023/12/21 21:25:39.566318 Running command tsc
src/modules/User/services.ts(15,26): error TS2307: Cannot find module '../mail/services' or its corresponding type declarations.
src/modules/User/services.ts(16,72): error TS2307: Cannot find module '../mail/templates' or its corresponding type declarations.
src/modules/User/services.ts(17,37): error TS2307: Cannot find module '../wallet/services' or its corresponding type declarations.
src/modules/auth/services.ts(6,39): error TS2307: Cannot find module '../authCode/services' or its corresponding type declarations.
src/modules/auth/services.ts(7,26): error TS2307: Cannot find module '../mail/services' or its corresponding type declarations.
src/modules/auth/services.ts(8,81): error TS2307: Cannot find module '../mail/templates' or its corresponding type declarations.
src/modules/auth/services.ts(9,44): error TS2307: Cannot find module '../user/services' or its corresponding type declarations.
src/modules/auth/services.ts(10,41): error TS2307: Cannot find module '../authCode/services' or its corresponding type declarations.
src/modules/quotation/services.ts(2,46): error TS2307: Cannot find module '../splitRisk/services' or its corresponding type declarations.
src/modules/quotation/services.ts(4,28): error TS2307: Cannot find module '../pricing/services' or its corresponding type declarations.
src/modules/quotation/types.ts(2,29): error TS2307: Cannot find module '../vehicle/types' or its corresponding type declarations.
src/routes.ts(6,27): error TS2307: Cannot find module './modules/coupons/routes' or its corresponding type declarations.
src/routes.ts(7,24): error TS2307: Cannot find module './modules/fipe/routes' or its corresponding type declarations.
src/routes.ts(8,32): error TS2307: Cannot find module './modules/pricingRules/routes' or its corresponding type declarations.
src/routes.ts(10,24): error TS2307: Cannot find module './modules/user/routes' or its corresponding type declarations.
src/routes.ts(11,27): error TS2307: Cannot find module './modules/vehicle/routes' or its corresponding type declarations.
src/types/request.ts(2,26): error TS2307: Cannot find module '../modules/user/types' or its corresponding type declarations.

[Container] 2023/12/21 21:25:44.189969 Command did not exit successfully tsc exit status 2
[Container] 2023/12/21 21:25:44.195064 Phase complete: BUILD State: FAILED
[Container] 2023/12/21 21:25:44.195079 Phase context status code: COMMAND_EXECUTION_ERROR Message: Error while executing command: tsc. Reason: exit status 2

buildspec.yml #

version: 0.2

phases:
  install:
    runtime-versions:
      nodejs: latest
    commands:
      - npm install -g typescript
      - npm install
  pre_build:
    commands:
      - pwd
      - npm ci --no-cache
  build:
    commands:
      - tsc

artifacts:
  files:
    - package.json
    - package-lock.json
    - 'build/**/*'
  discard-paths: yes

tsconfig.json #

{
  "compilerOptions": {
    "target": "es6",
    "module": "commonjs",
    "rootDir": "./",
    "outDir": "./build",
    "esModuleInterop": true,
    "strict": true,
    "types": ["node"]
  }
}

本地构建完全正常，为何这些TS2307错误仅出现在AWS CodeBuild环境中？

解决思路 #

1. 修复大小写不匹配问题 #

MacOS文件系统默认大小写不敏感，但CodeBuild使用的Linux环境严格区分大小写。看错误里的路径，比如../User/services.ts和仓库中实际的../user/services.ts，本地能识别但Linux下会找不到。

• 逐一检查所有import语句的路径大小写，确保和代码仓库中的文件/目录名完全一致，统一修正。

2. 清理依赖安装流程 #

当前buildspec中install阶段执行了npm install，pre_build又执行npm ci，可能导致依赖混乱。npm ci会严格按lock文件安装，不需要提前执行npm install。

• 修改buildspec的install阶段，去掉多余的npm install：

install:
  runtime-versions:
    nodejs: latest
  commands:
    - npm install -g typescript
pre_build:
  commands:
    - pwd
    - npm ci --no-cache

• 同时确认package.json中包含所有必要的@types/*依赖，尤其是项目内部模块的类型声明是否被正确配置。

3. 优化tsconfig配置 #

当前tsconfig的rootDir设为./，可能导致TypeScript无法正确识别需要编译的文件范围。

• 添加include字段明确指定编译范围，同时调整rootDir为./src（更合理的项目根目录）：

{
  "compilerOptions": {
    "target": "es6",
    "module": "commonjs",
    "rootDir": "./src",
    "outDir": "./build",
    "esModuleInterop": true,
    "strict": true,
    "types": ["node"]
  },
  "include": ["src/**/*", "types/**/*"],
  "exclude": ["node_modules", "build"]
}

4. 确认仓库文件完整性 #

检查本地是否有未提交的文件，比如错误中提到的../mail/services对应的文件，可能本地存在但没推送到远端，导致CodeBuild拉取的代码缺少这些文件。

• 执行git status查看未提交文件，确保所有被import的文件都已推送到代码仓库。

5. 统一TypeScript版本 #

本地全局TS版本和CodeBuild中安装的版本可能不一致，导致模块解析行为差异。

• 在package.json的devDependencies中添加固定版本的typescript，比如"typescript": "^5.3.3"；
• 修改buildspec的build命令，使用本地安装的TS而非全局版本：

build:
  commands:
    - npx tsc

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