新克隆的React+Vite项目执行npm run build时构建失败

项目配置 #

package.json #

{
  "name": "lava-sample-bot",
  "private": true,
  "version": "0.0.1",
  "type": "module",
  "homepage": "https://lava.dgordeev.online/payment",
  "scripts": {
    "build": "tsc -b --clean && tsc -b && vite build --debug",
    "buildv": "tsc --noEmit && vite build --debug",
    "lint": "eslint .",
    "dev": "tsx --watch --env-file .env src/server/bot/bot.ts & tsx --watch --env-file .env src/server/server-local.ts",
    "devm": "npm run dev & vite --open",
    "devdistbackend": "npm run startserver & npm run startbot",
    "startserver": "node --env-file .env dist/server/server.js",
    "startbot": "node --env-file .env dist/server/bot/bot.js",
    "startpm2": "pm2 start 'npm run startserver' && pm2 start 'npm run startbot' && pm2 save"
  },
  "dependencies": {
    "@grammyjs/menu": "github:grammyjs/menu",
    "@grammyjs/parse-mode": "^2.2.0",
    "@hawk.so/javascript": "^3.2.8",
    "@tailwindcss/vite": "^4.1.13",
    "@telegram-apps/sdk-react": "^3.3.6",
    "@telegram-apps/telegram-ui": "^2.1.9",
    "axios": "^1.12.1",
    "cors": "^2.8.5",
    "eruda": "^3.4.3",
    "express": "^5.1.0",
    "grammy": "^1.38.2",
    "greenlock-express": "^4.0.3",
    "https": "^1.0.0",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "react-router-dom": "^6.30.1"
  },
  "devDependencies": {
    "@eslint/js": "^9.23.0",
    "@types/cors": "^2.8.19",
    "@types/express": "^5.0.3",
    "@types/node": "^20.19.11",
    "@types/react": "^18.3.24",
    "@types/react-dom": "^18.3.7",
    "@typescript-eslint/eslint-plugin": "^8.28.0",
    "@typescript-eslint/parser": "^8.28.0",
    "@vitejs/plugin-react-swc": "^3.11.0",
    "cross-env": "^7.0.3",
    "eslint": "^9.34.0",
    "eslint-plugin-react": "^7.37.5",
    "eslint-plugin-react-hooks": "^5.2.0",
    "gh-pages": "^6.3.0",
    "globals": "^15.15.0",
    "tailwindcss": "^4.1.13",
    "tsx": "^4.20.5",
    "typescript": "^5.9.2",
    "typescript-eslint": "^8.40.0",
    "vite": "^6.3.5",
    "vite-plugin-mkcert": "^1.17.8",
    "vite-tsconfig-paths": "^5.1.4"
  }
}

tsconfig.json #

{
  "files": [],
  "references": [
    { "path": "./tsconfig.server.json" },
    { "path": "./tsconfig.miniapp.json" },
  ],
}

tsconfig.miniapp.json #

{
    "compilerOptions": {
        "allowImportingTsExtensions": true,
        "isolatedModules": true,
        "jsx": "react-jsx",
        "lib": [
            "ES2023",
            "DOM",
            "DOM.Iterable"
        ],
        "module": "ESNext",
        "moduleResolution": "bundler",
        "noEmit": true,
        "noFallthroughCasesInSwitch": true,
        "noUnusedLocals": true,
        "noUnusedParameters": true,
        "paths": {
            "@/*": [
                "./src/miniapp/*"
            ]
        },
        "resolveJsonModule": true,
        "skipLibCheck": true,
        "strict": true,
        "target": "ES2023",
        "useDefineForClassFields": true,
        "types": [
            "vite/client"
        ]
    },
    "include": [
        "vite.config.ts",
        "src/miniapp/",
        "src/domain/**/*.ts"
    ],
}

报错信息 #

执行npm run build时出现以下错误：

✗ Build failed in 582ms
error during build:
[vite:esbuild-transpile] Transform failed with 7 errors:
assets/index-!~{001}~.js:2953:5: ERROR: The symbol "je" has already been declared
assets/index-!~{001}~.js:3335:185: ERROR: The symbol "be" has already been declared
assets/index-!~{001}~.js:3532:79: ERROR: The symbol "N" has already been declared
assets/index-!~{001}~.js:3594:9: ERROR: The symbol "Ie" has already been declared
assets/index-!~{001}~.js:3764:76: ERROR: The symbol "Ne" has already been declared
...
file: assets/index-!~{001}~.js:2953:5

环境信息 #

• Node.js: 23.7.0
• npm: 10.9.2
• React: 18.3.1
• @telegram-apps/sdk-react: 3.3.6
• Vite: 6.3.6
• esbuild: 0.25.9

该问题在OS X与Ubuntu系统上均会出现。

已尝试的解决方法 #

• 删除node_modules与package-lock.json后重新安装依赖
• 调整Vite、npm、Node.js、esbuild的版本

异常现象 #

原开发目录中执行构建一切正常，但将项目从Git仓库克隆到新目录后就会触发上述错误。

解决思路与方案 #

1. 检查Git忽略配置 #

原目录正常但新克隆目录报错，核心原因是新旧目录的构建环境不一致，优先排查.gitignore：

• 确认.gitignore包含dist/、.vite/、*.tsbuildinfo、node_modules/，避免新目录残留旧缓存或未提交的本地文件
• 对比原目录和新克隆目录的所有配置文件（如vite.config.ts、.env），确保无本地未提交的修改

2. 替换或调整ESbuild压缩配置 #

报错中的短变量名是ESbuild压缩时生成的命名冲突，可通过以下方式解决：

• 在vite.config.ts中将压缩工具替换为terser：

import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    minify: 'terser',
  },
});

• 若坚持使用ESbuild，可禁用标识符混淆：

import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    esbuild: {
      minifyIdentifiers: false,
    },
  },
});

3. 优化TypeScript项目引用的构建流程 #

项目使用TypeScript项目引用，需确保服务端与客户端构建完全隔离：

• 修改build脚本，明确指定先构建服务端，再构建客户端：

"scripts": {
  "build": "tsc -b --clean && tsc -b src/server && vite build --debug"
}

• 检查tsconfig.server.json的outDir，确保其与Vite的build.outDir（默认dist）完全分离，避免产物交叉覆盖

4. 锁定依赖版本避免重复引入 #

部分依赖可能存在多版本安装导致的代码重复：

• 执行npm ls @telegram-apps/sdk-react和npm ls @telegram-apps/telegram-ui，检查是否存在多个版本
• 在package.json中添加resolutions字段锁定依赖版本：

"resolutions": {
  "@telegram-apps/sdk-react": "3.3.6",
  "@telegram-apps/telegram-ui": "2.1.9"
}

5. 手动清理构建缓存 #

新克隆目录可能存在异常缓存，执行以下命令清理后重新构建：

# Linux/macOS
rm -rf .vite/ dist/ node_modules/ package-lock.json
npm install
npm run build

# Windows
rmdir /s /q .vite dist node_modules
del package-lock.json
npm install
npm run build

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