ZAPlayer/BUILD_TROUBLESHOOTING.md

ZAPlayer 构建故障排除指南

常见问题解决

1. Terser 依赖错误

错误信息：

error during build: [vite:terser] terser not found. Since Vite v3, terser has become an optional dependency. You need to install it.

解决方案：

方案A：使用简化构建（推荐）

# 使用不需要terser的简化配置
npm run build:simple

方案B：安装terser依赖

# 安装terser依赖
npm run install:terser

# 然后正常构建
npm run build:min

方案C：手动安装terser

npm install --save-dev terser
npm run build:min

2. 构建配置选择

我们提供了多个构建配置：

配置文件	用途	特点
vite.lib.simple.config.js	简化构建	使用Vite内置压缩，无需额外依赖
vite.lib.config.js	高级构建	使用terser，压缩效果更好

3. 构建输出文件

成功构建后，会在 dist/ 目录下生成：

• za-player.min.js - UMD格式，浏览器使用
• za-player.es.js - ES模块格式，现代项目使用

4. 验证构建结果

构建完成后，可以通过以下方式验证：

检查文件是否存在

ls -la dist/
# Windows: dir dist\

检查文件大小

# 查看文件大小（应该有一定压缩）
wc -c dist/za-player.min.js
wc -c dist/za-player.es.js

测试功能

打开 test-build.html 文件，在浏览器中测试两个构建文件是否正常工作。

5. 快速开始（推荐流程）

# 1. 安装依赖
npm install

# 2. 使用简化构建（避免terser问题）
npm run build:simple

# 3. 验证构建结果
ls dist/
# 应该看到 za-player.min.js 和 za-player.es.js

# 4. 测试功能
# 在浏览器中打开 test-build.html

6. 如果仍然有问题

1. 清除node_modules并重新安装：

   rm -rf node_modules package-lock.json
   npm install
   

2. 检查Node.js版本：

   node --version
   # 建议使用 Node.js 16+ 
   

3. 检查Vite版本：

   npm list vite
   

4. 查看详细错误信息：

   npm run build:simple -- --debug
   

7. 获取帮助

如果以上方法都不能解决问题，请提供以下信息：

1. 完整的错误信息
2. Node.js版本 (node --version)
3. npm版本 (npm --version)
4. 操作系统信息
5. 使用的构建命令