Docker Build本地Mac正常但GitLab CI(Ubuntu)失败的TS依赖问题排查

你遇到的问题根源其实很清晰：MacOS与Ubuntu文件系统的大小写敏感性差异。

问题原因 #

MacOS默认使用的APFS/HFS+文件系统是大小写不敏感的——哪怕实际文件名是Contact.ts，你写./contact也能正常识别；但Ubuntu采用的ext4文件系统是严格大小写敏感的，当TypeScript代码里的导入路径大小写和实际文件名不匹配时，TS编译器就会抛出TS2307: Cannot find module错误。

你本地Mac和Node环境测试正常，就是因为这个大小写不敏感的特性帮你“掩盖”了问题，到了Ubuntu环境就直接暴露出来了。

具体解决方案 #

1. 统一导入路径与文件名的大小写

这是最根本的解决办法：

• 逐个检查报错的导入语句，比如src/contact/contact.mapper.ts里的import ... from './contact'，找到对应的实际文件（比如可能是Contact.ts、contact.model.ts或者大小写混合的文件名），把导入路径改成和实际文件名完全一致的大小写。
• 为了避免后续再出现这类问题，建议在团队内约定统一的文件名命名规范（比如全部小写、小驼峰或大驼峰），并且可以在本地用Docker模拟Linux环境跑tsc --noEmit，提前检查这类大小写不匹配的问题。

2. 可选：在Dockerfile中添加前置检查（提前拦截问题）

可以在RUN npm run build之前添加一段shell脚本，自动检查所有TS文件的导入路径是否匹配实际文件的大小写，避免等到编译阶段才报错：

FROM node:11.13.0-alpine
WORKDIR /usr/src/app/
COPY . .
RUN npm install
# 添加大小写检查脚本
RUN find src -name "*.ts" -exec grep -l "import.*from './.*'" {} \; | while read file; do
  grep -E "import.*from '(\.\/[^']+)'" "$file" | while read -r line; do
    module_path=$(echo "$line" | sed -E "s/import.*from '(\.\/[^']+)'/\1/")
    # 检查常见的TS文件扩展名
    for ext in .ts .tsx .d.ts; do
      if [ -f "$(dirname "$file")/$module_path$ext" ]; then
        continue 2
      fi
    done
    echo "FATAL: Module path '$module_path' in file '$file' does not match any existing file (case-sensitive check failed)"
    exit 1
  done
done
RUN npm run build
CMD ["node", "dist/main.js"]

3. GitLab CI配置的小优化（可选）

虽然和当前报错无关，但可以优化你的CI构建效率：

• 添加npm依赖缓存，避免每次构建都重新安装依赖：

  image: ubuntu:bionic
  stages:
    - deploy
  cache:
    paths:
      - node_modules/
  before_script:
    # 合并apt安装命令，减少构建步骤
    - apt-get update && apt-get install -y gnupg2 software-properties-common docker.io curl
    - service docker start
  deploy:
    stage: deploy
    script:
      - docker build -t my_app .
      # 其他操作
  

验证方法 #

你可以先在本地Ubuntu虚拟机里修正代码的大小写问题，再执行docker build -t my_app .确认构建成功，之后推送代码到GitLab，CI构建应该就能正常通过了。

内容的提问来源于stack exchange，提问作者Héctor Valls