ng build在TeamCity的Docker构建中失败，本地执行正常

我将Angular应用构建至Docker容器中，对应的Dockerfile内容如下：

FROM node:12.22.12 AS build

ARG STAGE=dev
ENV STAGE=${STAGE}

WORKDIR /usr/src/app
COPY package.json ./

RUN apt-get update || : && apt-get install python -y

RUN npm install
COPY . .
RUN npm run build-${STAGE}

FROM nginx:1.17.1-alpine
COPY nginx-site.conf /etc/nginx/conf.d/default.conf
COPY --from=build /usr/src/app/dist /usr/share/nginx/html

本地执行以下构建命令可成功完成：

docker build -t spa-application --build-arg=STAGE=prod .

但在TeamCity服务器上执行完全相同的命令时，ng build-prod阶段出现编译错误，错误提示为：

ERROR in The Angular Compiler requires TypeScript >=4.0.0 and <4.1.0 but 4.9.5 was found instead.

该构建此前在TeamCity上正常运行数月，最后一次成功构建为9月，我不清楚本地与TeamCity环境的差异所在，请问问题可能出在哪里？

1. 依赖版本未锁定，导致拉取不兼容的TypeScript版本 #

如果你的package.json中TypeScript的版本声明是宽松范围（比如^3.9.x或~4.0.x），npm会自动拉取满足范围的最新版本，而Angular编译器对TypeScript版本有严格区间限制。本地可能因package-lock.json锁定了版本，而TeamCity构建时未使用锁定文件，或锁定文件未提交到仓库。

• 解决步骤：
  • 确认package-lock.json（或yarn.lock）已提交到代码仓库，若未提交则立即提交
  • 将Dockerfile中的RUN npm install替换为RUN npm ci，npm ci会严格按照lock文件安装依赖，避免版本漂移
  • 修改package.json中TypeScript的版本为Angular兼容的固定版本，比如"typescript": "4.0.8"（需匹配你项目Angular版本的兼容区间）

2. Docker构建层缓存导致依赖未更新 #

TeamCity可能复用了之前构建的Docker层，即使package.json有变化，也未重新执行npm install步骤，导致依赖版本仍为旧版或不兼容版本。

• 解决步骤：
  • 在TeamCity的构建命令中添加--no-cache参数，强制重新构建所有层：

    docker build --no-cache -t spa-application --build-arg=STAGE=prod .
    

3. TeamCity的npm源或网络环境变化 #

如果TeamCity使用私有npm源，或源地址更新、网络波动导致拉取的依赖版本与本地不一致，比如拉取了错误的TypeScript版本。

• 解决步骤：
  • 在Dockerfile中指定稳定的npm源，添加在npm install之前：

    RUN npm config set registry https://registry.npmmirror.com/
    

  • 检查TeamCity构建代理的网络设置，确认能正常访问指定的npm源

4. 代码仓库混入本地修改的依赖配置 #

比如本地修改了package.json的版本声明但未提交，或.npmrc文件配置不同，导致TeamCity构建时使用了不同的依赖版本。

• 解决步骤：
  • 检查本地代码与仓库代码的差异，确保package.json、package-lock.json、.npmrc等配置文件完全一致
  • 在TeamCity构建前添加代码校验步骤，确保没有未提交的修改

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