Playwright/TypeScript项目Docker部署路径映射报错求助

问题根源 #

Node.js和Playwright默认不会自动解析tsconfig.json中的路径别名（比如@extensions/APIActions），Docker环境下如果没有额外配置，就会出现模块找不到的错误。下面提供两种实用解决方案：

方案1：运行时通过tsconfig-paths解析别名（快速调试） #

适合不想编译TS文件，直接运行测试的场景：

1. 安装依赖

npm install --save-dev tsconfig-paths

2. 修改package.json的测试命令
   在Playwright启动时加载tsconfig-paths/register模块，让Node.js识别路径别名：

{
  "scripts": {
    "test": "cross-env ENV=your_environment npx playwright test --require tsconfig-paths/register"
  }
}

3. 调整Dockerfile
   确保tsconfig.json被复制到容器中，完整示例：

# 使用官方Playwright镜像（包含所有浏览器依赖）
FROM mcr.microsoft.com/playwright:v1.40.0-jammy

WORKDIR /app

# 先复制依赖文件，利用Docker缓存优化构建速度
COPY package*.json ./
RUN npm ci

# 复制tsconfig和测试代码
COPY tsconfig.json ./
COPY tests ./tests

# 执行测试命令
CMD ["npm", "run", "test"]

方案2：编译时转换别名（推荐CI/生产环境） #

通过tsc-alias将TS编译为JS时，把路径别名替换成相对路径，运行时无需额外配置：

1. 安装依赖

npm install --save-dev tsc-alias

2. 配置tsconfig.json
   确保指定编译输出目录，路径别名配置正确：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@extensions/*": ["./tests/extensions/*"]
    },
    "outDir": "./dist", // 指定编译后文件输出目录
    "module": "CommonJS",
    "target": "ES2020"
  },
  "include": ["tests/**/*"]
}

3. 修改package.json脚本
   添加编译命令，测试时运行编译后的JS文件：

{
  "scripts": {
    "build": "tsc && tsc-alias", // 编译+替换别名
    "test": "cross-env ENV=your_environment npx playwright test dist/tests"
  }
}

4. 调整Dockerfile
   先完成编译再执行测试：

FROM mcr.microsoft.com/playwright:v1.40.0-jammy

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY tsconfig.json ./
COPY tests ./tests

# 先编译TS文件并替换别名
RUN npm run build

CMD ["npm", "run", "test"]

关键检查点 #

• 确认tsconfig.json的paths映射和实际文件路径完全匹配（比如@extensions/APIActions对应./tests/extensions/APIActions.ts）
• Dockerfile必须复制tsconfig.json，否则容器内无法读取路径别名配置
• 用npm ci替代npm install，确保容器内依赖版本和本地一致

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