检查 Node.js 版本

确保系统安装的 Node.js 版本符合 LLaMa-Factory 的要求。推荐使用 Node.js 16.x 或 18.x 版本。可通过以下命令验证版本：

node -v

若版本不匹配，需升级或降级 Node.js。可通过 nvm（Node Version Manager）管理多版本：

nvm install 18
nvm use 18

清理并重新安装依赖

删除现有 node_modules 和 package-lock.json 文件，重新安装依赖：

rm -rf node_modules package-lock.json
npm install

若网络问题导致安装失败，可切换为国内镜像源：

npm config set registry https://registry.npmmirror.com

检查端口冲突

默认情况下，LLaMa-Factory 的 WebUI 运行在 http://localhost:7860。确认该端口未被其他程序占用：

lsof -i :7860

若端口冲突，可通过修改 webui.py 或启动参数指定其他端口：

python src/llamafactory/cli/webui.py --port 7870

验证前端构建

手动构建前端静态文件，确保无编译错误：

npm run build

构建成功后，检查生成的 dist 目录是否完整。若存在构建错误，需根据终端输出的日志修复对应问题。

检查后端服务状态

前端依赖后端服务提供 API 支持。确保后端服务已正常启动：

python src/llamafactory/api.py

验证后端接口是否可访问：

curl http://localhost:8000/api/status

查看浏览器控制台日志

若页面空白或加载异常，打开浏览器开发者工具（F12），查看 Console 和 Network 选项卡中的错误信息。常见问题包括：

• 404 错误：静态资源路径配置错误
• 500 错误：后端 API 调用失败
• CORS 问题：需配置后端允许跨域

更新依赖版本

若问题持续存在，尝试升级关键依赖：

npm update
npm install react-scripts@latest

同步更新 Python 后端依赖：

pip install -r requirements.txt --upgrade

环境变量配置

某些情况下需配置环境变量。创建 .env 文件并添加必要配置：

VITE_API_BASE_URL=http://localhost:8000
NODE_ENV=development

系统权限问题

在 Linux/macOS 系统中，若出现权限错误，尝试以管理员权限运行：

sudo npm install

或修正目录权限：

sudo chown -R $(whoami) node_modules