常见问题

收集项目开发中的常见问题和解决方案。

安装和启动

依赖安装失败

问题：pnpm install 失败

解决方案：

# 清除缓存
pnpm store prune

# 删除依赖
rm -rf node_modules pnpm-lock.yaml

# 重新安装
pnpm install

浏览器空白

问题：启动后浏览器显示空白

解决方案：

• 升级浏览器到最新版本
• 检查控制台错误信息
• 清除浏览器缓存

端口被占用

问题：端口 3000 被占用

解决方案：

# 修改端口
# 在 .env.development 中修改 VITE_APP_PORT

# 或杀死占用端口的进程
# Windows
netstat -ano | findstr 3000
taskkill /PID <PID> /F

# Mac/Linux
lsof -i :3000
kill -9 <PID>

开发问题

组件自动导入失败

问题：组件没有自动导入

解决方案：

• 重启开发服务器
• 检查组件路径
• 检查 vite.config.ts 配置

类型提示不生效

问题：TypeScript 类型提示不工作

解决方案：

• 重启 VSCode
• 检查 tsconfig.json 配置
• 确保 TypeScript 版本 >= 5.0

热更新失败

问题：修改代码后页面不更新

解决方案：

• 重启开发服务器
• 检查文件保存成功
• 清除浏览器缓存

权限问题

路由跳转 404

问题：跳转路由显示 404

解决方案：

• 检查路由配置
• 确认用户有访问权限
• 检查动态路由是否正确添加

按钮权限不生效

问题：v-hasPerm 指令不生效

解决方案：

• 检查权限标识是否正确
• 确认用户权限已正确获取
• 检查指令注册是否正确

构建和部署

构建失败

问题：pnpm run build 报错

解决方案：

• 检查代码是否有语法错误
• 检查 TypeScript 类型错误
• 升级依赖到最新版本

部署后页面空白

问题：部署到服务器后页面空白

解决方案：

• 检查 Nginx 配置
• 确认文件上传完整
• 检查 API 接口地址配置

刷新 404

问题：部署后刷新页面 404

解决方案：

# 在 Nginx 配置中添加
location / {
    try_files $uri $uri/ /index.html;
}

其他问题

登录失败

问题：无法登录系统

解决方案：

• 检查用户名密码是否正确
• 检查 API 接口地址
• 查看网络请求错误信息

Mock 不生效

问题：开启 Mock 后仍请求真实接口

解决方案：

• 确认 .env.development 中 VITE_MOCK_DEV_SERVER = true
• 重启开发服务器
• 检查 Mock 文件配置

获取帮助

如果以上方案无法解决问题：

1. 查看文档：仔细阅读相关文档
2. 搜索 Issues：在 Gitee Issues 搜索类似问题
3. 提交 Issue：描述问题并提供错误信息
4. 加入交流群：关注「有来技术」公众号获取交流群二维码

相关链接

• 快速开始
• 项目结构
• 环境配置
• 构建和部署