Phaser3项目Vercel部署失败问题（已更新）

问题情况 #

用Vite+React+TypeScript开发的项目，本地执行build或preview命令均能正常运行，但Vercel部署时触发以下错误：

错误日志：

11:57:49.482 error TS2688: Cannot find type definition file for 'Phaser
11:57:49.482   The file is in the program because:
11:57:49.483     Entry point of type library 'Phaser' specified in compileroptions
11:57:49.500   ELIFECYCLE Command failed with exit code 2.
11:57:49.526 Error: Command "pnpm run build" exited with 1
11:57:50.217 Deployment completed
11:57:49.841 BUILD_UTILS_SPAWN_1: Command "pnpm run build" exited with 1

同时用Docker本地构建也遇到完全相同的错误。

当前配置文件 #

tsconfig.json #

{  
  "compilerOptions": {    
    "target": "ESNext",    
    "lib": ["DOM", "DOM.Iterable", "ESNext","es6", "dom", "dom.iterable", "scripthost"],    
    "typeRoots": ["./node_modules/@types","./node_modules/phaser/types"],    
    "types": ["Phaser"],    
    "module": "ESNext",    
    "skipLibCheck": true,    
    /* Bundler mode */    
    "moduleResolution": "bundler",    
    "allowImportingTsExtensions": true,    
    "resolveJsonModule": true,    
    "isolatedModules": true,    
    "noEmit": true,    
    "jsx": "react-jsx",

    /* Linting */    
    "strict": true,    
    "noUnusedLocals": true,    
    "noUnusedParameters": true,    
    "noFallthroughCasesInSwitch": true  
  },  
  "files": ["./node_modules/phaser/types/phaser.d.ts"],  
  "include": ["src"],  
  "references": [{ "path": "./tsconfig.node.json" }]
}

docker-compose.yml #

version: '3'
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - 3000:3000
    volumes:
      - .:/app
      - /app/node_modules

Dockerfile #

# Base image
FROM node:16-alpine

# Set the working directory
WORKDIR /app

# Copy package.json and pnpm-lock.yaml to the container
COPY package.json pnpm-lock.yaml ./

# Install dependencies
RUN npm install -g pnpm && pnpm install

# Copy the rest of the application files to the container
COPY . .

# Build the application
RUN pnpm run build

# Expose the port
EXPOSE 3000
# Start the application
CMD ["pnpm", "run", "preview"]

解决方法 #

1. 修正TypeScript配置 #

问题核心是tsconfig对Phaser类型的配置存在硬编码和大小写问题，本地环境依赖缓存或路径巧合正常，但容器/部署环境中暴露了问题：

• 移除硬编码类型文件路径：删掉files字段里的./node_modules/phaser/types/phaser.d.ts，Phaser自带类型定义，TypeScript会自动识别，硬编码路径会在依赖重装后失效
• 修正类型包大小写：把types里的"Phaser"改成小写"phaser"，TypeScript查找类型时严格区分大小写，Phaser的类型标识是小写
• 简化typeRoots配置：移除typeRoots中的./node_modules/phaser/types，TypeScript默认会扫描node_modules下的类型目录，手动指定容易引发路径冲突

修正后的关键配置片段：

{
  "compilerOptions": {
    // ...其他原有配置
    "typeRoots": ["./node_modules/@types"],
    "types": ["phaser"]
    // ...其他原有配置
  },
  "include": ["src"],
  "references": [{ "path": "./tsconfig.node.json" }]
}

2. 确保依赖安装无遗漏 #

• 确认package.json中已正确添加phaser依赖，版本无误
• Docker构建时，当前Dockerfile的pnpm install会安装所有依赖（包括开发依赖），不要随意添加--production参数，否则会丢失TypeScript类型相关依赖
• Vercel部署时，在项目设置的「Build & Development Settings」里指定包管理器为pnpm，确保平台完整安装所有依赖

3. 验证修复效果 #

先在本地执行pnpm install && pnpm run build确认构建成功，再重新构建Docker镜像或触发Vercel部署，问题即可解决。

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