ruoyi-miniapp/.cursor/rules/troubleshooting.mdc

---
description: 
globs: 
alwaysApply: false
---
# 智慧生态项目常见问题排查指南

## 登录相关问题

### Token 失效处理
问题：用户 Token 过期后的处理
解决方案：
1. 在 [request.js](mdc:utils/request.js) 中检测 401 错误
2. 清除本地 Token：`removeToken()`
3. 跳转到登录页：`uni.reLaunch({ url: '/pages/login' })`

### 权限拦截不生效
问题：页面权限拦截失效
检查点：
1. 确认 [permission.js](mdc:permission.js) 已在 [main.js](mdc:main.js) 中引入
2. 检查页面路径是否在白名单中
3. 确认使用了正确的跳转方法（navigateTo、redirectTo 等）

## API 请求问题

### 跨域问题
在开发环境中遇到跨域：
1. H5 开发：在 [manifest.json](mdc:manifest.json) 配置代理
2. 小程序：在小程序开发工具中关闭域名校验
3. 生产环境：确保服务器配置了正确的 CORS 头

### 请求超时
调整请求超时时间：
```javascript
// 在 request.js 中设置
const service = uni.request({
  timeout: 10000 // 10秒超时
})
```

## 小程序特定问题

### 包体积超限
解决方案：
1. 使用分包加载，配置在 [pages.json](mdc:pages.json)
2. 压缩图片资源
3. 移除未使用的代码和依赖
4. 使用 CDN 加载大型资源

### 真机调试问题
1. 确保 [config.js](mdc:config.js) 中的 baseUrl 使用 HTTPS
2. 在小程序管理后台配置合法域名
3. 检查 [manifest.json](mdc:manifest.json) 中的权限申请

### 小程序授权失败
检查：
1. `manifest.json` 中的 `permission` 配置
2. `requiredPrivateInfos` 是否声明了需要的接口
3. 用户是否拒绝了授权

## 样式问题

### 样式不生效
1. 检查是否使用了 `scoped`
2. uni-app 不支持的 CSS 选择器
3. 使用 `/deep/` 或 `::v-deep` 穿透组件样式

### rpx 单位问题
```scss
// 使用 uni.scss 中的变量
@import '@/uni.scss';

.container {
  padding: 20rpx; // 自动适配不同屏幕
}
```

## 状态管理问题

### Vuex 数据不更新
1. 确认使用了 `commit` 提交 mutation
2. 检查是否正确使用了命名空间
3. 使用 `mapState`、`mapGetters` 辅助函数

### 页面刷新数据丢失
解决方案：
1. 重要数据持久化到 storage
2. 在 `onShow` 生命周期重新获取数据
3. 使用 Vuex 配合持久化插件

## 性能优化

### 页面加载慢
1. 减少首屏加载的数据量
2. 使用图片懒加载
3. 分页加载列表数据
4. 使用骨架屏提升体验

### 列表滚动卡顿
```vue
<scroll-view 
  scroll-y 
  :show-scrollbar="false"
  :enhanced="true"
  :bounces="false">
  <!-- 使用虚拟列表或分页加载 -->
</scroll-view>
```

## 开发环境问题

### HBuilderX 相关
1. 确保使用最新版本的 HBuilderX
2. 清理项目缓存：工具 -> 清理缓存
3. 重启 HBuilderX 和开发者工具

### 依赖安装问题
```powershell
# 清理缓存
Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json

# 重新安装
npm install
```

## 调试技巧

### 查看网络请求
1. 小程序：使用开发者工具的 Network 面板
2. H5：使用浏览器开发者工具
3. APP：使用 `console.log` 或远程调试

### 查看存储数据
```javascript
// 获取所有存储的键
const res = uni.getStorageInfoSync()
console.log('keys:', res.keys)

// 查看特定数据
const token = uni.getStorageSync('token')
console.log('token:', token)
```

### 页面栈信息
```javascript
// 获取当前页面栈
const pages = getCurrentPages()
console.log('页面栈:', pages)

// 获取当前页面实例
const currentPage = pages[pages.length - 1]
```

## 发布部署

### 小程序发布前检查
1. 关闭调试模式
2. 检查 API 地址是否正确
3. 压缩代码和资源
4. 测试各项权限申请

### 版本更新提示
```javascript
// 在 App.vue 中添加
onShow() {
  // #ifdef MP-WEIXIN
  const updateManager = uni.getUpdateManager()
  updateManager.onUpdateReady(() => {
    uni.showModal({
      title: '更新提示',
      content: '新版本已经准备好，是否重启应用？',
      success: (res) => {
        if (res.confirm) {
          updateManager.applyUpdate()
        }
      }
    })
  })
  // #endif
}