常见问题

安装问题

依赖安装失败

问题： pnpm install 失败

解决方案：

# 清除缓存
pnpm store prune
rm -rf node_modules pnpm-lock.yaml

# 重新安装
pnpm install

Node 版本不兼容

问题： The engine "node" is incompatible

解决方案：

确保 Node.js 版本 >= 18.0

# 查看当前版本
node -v

# 使用 nvm 切换版本
nvm install 18
nvm use 18

启动问题

后端启动失败

问题： 数据库连接失败

解决方案：

1. 检查 MySQL 是否运行
2. 检查数据库配置是否正确
3. 确认数据库已创建并导入 SQL 脚本

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/vben_admin
    username: root
    password: your_password

问题： Redis 连接失败

解决方案：

1. 检查 Redis 是否运行
2. 检查 Redis 配置是否正确

# 启动 Redis
redis-server

# 测试连接
redis-cli ping

前端启动失败

问题： 端口被占用

解决方案：

修改 vite.config.mts 中的端口：

export default defineConfig({
  server: {
    port: 5174, // 修改为其他端口
  }
})

问题： 模块找不到

解决方案：

# 重新安装依赖
pnpm install

# 清除缓存
rm -rf node_modules/.vite

功能问题

登录失败

问题： 用户名或密码错误

解决方案：

1. 检查数据库中的用户数据
2. 确认密码是否正确（默认：123456）
3. 检查用户状态是否启用

问题： Token 失效

解决方案：

1. 检查 Sa-Token 配置
2. 清除浏览器缓存和 LocalStorage
3. 重新登录

文件上传失败

问题： 文件大小超限

解决方案：

修改后端配置：

spring:
  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 100MB

问题： 文件类型不支持

解决方案：

检查前端 accept 配置和后端文件类型验证。

Excel 导入导出问题

问题： 导出的 Excel 打不开

解决方案：

1. 检查 EasyExcel 版本
2. 确认实体类注解配置正确
3. 检查响应头设置

response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
response.setCharacterEncoding("utf-8");

问题： 导入数据验证失败

解决方案：

1. 检查 Excel 模板格式
2. 确认数据格式正确
3. 添加详细的错误提示

权限问题

菜单不显示

问题： 登录后看不到菜单

解决方案：

1. 检查用户角色权限
2. 确认菜单数据已正确配置
3. 检查路由权限配置

接口无权限

问题： 403 Forbidden

解决方案：

1. 检查 Sa-Token 配置
2. 确认用户拥有对应权限
3. 检查接口权限注解

@SaCheckPermission("user:list")
@GetMapping("/list")
public R<List<User>> list() {
    return R.ok(userService.list());
}

性能问题

页面加载慢

解决方案：

1. 启用代码分割和懒加载
2. 优化图片和资源大小
3. 使用 CDN 加速
4. 启用 Gzip 压缩

接口响应慢

解决方案：

1. 添加数据库索引
2. 使用 Redis 缓存
3. 优化 SQL 查询
4. 使用分页查询

部署问题

前端部署

问题： 打包后白屏

解决方案：

1. 检查 base 配置
2. 确认资源路径正确
3. 检查浏览器控制台错误

export default defineConfig({
  base: '/admin/', // 根据实际部署路径配置
})

问题： 刷新 404

解决方案：

配置 Nginx：

location / {
  try_files $uri $uri/ /index.html;
}

后端部署

问题： JAR 包启动失败

解决方案：

1. 检查 Java 版本
2. 确认配置文件正确
3. 查看日志文件

# 启动并查看日志
java -jar vben-admin.jar > app.log 2>&1 &

# 查看日志
tail -f app.log

开发问题

热更新不生效

解决方案：

1. 检查 Vite 配置
2. 重启开发服务器
3. 清除浏览器缓存

TypeScript 类型错误

解决方案：

1. 更新类型定义文件
2. 检查 tsconfig.json 配置
3. 重启 IDE

样式不生效

解决方案：

1. 检查 CSS 作用域
2. 确认样式优先级
3. 检查 Tailwind 配置

其他问题

如何自定义主题？

参考 主题定制 文档。

如何添加新页面？

参考 路由配置 文档。

如何添加新接口？

参考 后端开发 文档。

如何国际化？

参考 国际化 文档。

获取帮助

如果以上方案无法解决您的问题，可以通过以下方式获取帮助：

• 📚 查看 完整文档
• 💬 提交 GitHub Issue
• 📧 联系技术支持
• 💡 查看 示例代码

相关链接

• 快速开始
• 项目结构
• 最佳实践