通过GitLab流水线部署Angular应用到Heroku时无法识别组件报错

1. 对齐多端环境版本 #

• 绝大多数本地构建正常、线上流水线报错的问题根源都是环境版本差异。需保证本地开发环境、GitLab Runner运行环境、Heroku部署环境的Node.js版本、包管理器（npm/yarn/pnpm）版本、Angular CLI版本完全一致。
• 可在package.json中新增engines字段，明确指定Heroku使用的Node.js和包管理器版本，避免其使用默认浮动版本：

{
  "engines": {
    "node": "你的本地Node.js版本号，比如18.17.0",
    "npm": "你的本地npm版本号，比如9.6.7"
  }
}

• 同时在.gitlab-ci.yml中显式指定和本地版本一致的Node.js镜像，禁止使用node:latest这类无固定版本的镜像标签。

2. 校验大小写敏感问题 #

• Windows、macOS系统默认文件系统大小写不敏感，而GitLab Runner和Heroku通常运行在大小写敏感的Linux环境中。如果你的组件/模块导入路径的大小写和实际文件名不一致，本地不会触发报错，但线上会直接抛出模块找不到的错误。
• 可在tsconfig.json的compilerOptions中开启forceConsistentCasingInFileNames配置，本地开发阶段就强制校验路径大小写：

{
  "compilerOptions": {
    "forceConsistentCasingInFileNames": true
  }
}

3. 检查代码提交完整性 #

• 确认你没有将angular.json、tsconfig.json、各类环境配置文件等项目必要配置加入.gitignore，导致流水线拉取的代码缺少核心配置，触发编译异常。
• 检查是否存在仅在本地配置的私有依赖、软链接依赖，这类依赖如果没有配置对应的私有源访问权限，流水线安装依赖时会缺失对应包，引发模块报错。

4. 对齐依赖安装逻辑 #

• 保证流水线依赖安装命令和本地完全一致，且将对应包管理器的lock文件（package-lock.json/yarn.lock/pnpm-lock.yaml）提交到代码仓库。
• 流水线安装依赖优先使用npm ci、yarn install --frozen-lockfile这类完全基于lock文件安装的命令，而非npm install这类允许版本浮动的命令，保证线上依赖版本和本地完全对齐。

5. 开启详细日志定位问题 #

• 在.gitlab-ci.yml的构建命令中添加--verbose参数，输出完整的构建日志，可直接定位到具体报错的组件和模块：

ng build --configuration production --verbose

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