front-end/.cursor/rules/debugging-help.mdc

---
alwaysApply: false
---

### 调试和问题排查

#### 常见问题和解决方案

**1. 页面跳转问题**
```javascript
// 问题：页面跳转失败
// 原因：路径错误、页面未在 pages.json 中注册

// 解决方案：
// 1. 检查路径是否正确（以 / 开头）
uni.navigateTo({
  url: '/pages/order/detail?id=123'  // 正确
  // url: 'pages/order/detail'       // 错误：缺少前导斜杠
})

// 2. 确保页面已在 pages.json 中注册
{
  "pages": [
    {
      "path": "pages/order/detail",
      "style": {
        "navigationBarTitleText": "订单详情"
      }
    }
  ]
}

// 3. 检查跳转层级限制（小程序最多10层）
```

**2. 网络请求问题**
```javascript
// 问题：请求失败 fail statusCode:600
// 原因：域名未配置、SSL证书问题

// 调试方法：
// 1. 检查 manifest.json 中的域名配置
"h5": {
  "devServer": {
    "proxy": {
      "/api": {
        "target": "https://your-api.com",
        "changeOrigin": true
      }
    }
  }
}

// 2. 小程序开发时设置不校验域名
// 微信开发者工具 -> 设置 -> 项目设置 -> 不校验合法域名

// 3. 添加请求日志
uni.request({
  url: 'https://api.example.com/data',
  success: (res) => {
    console.log('请求成功:', res)
  },
  fail: (err) => {
    console.error('请求失败:', err)
    console.error('错误码:', err.statusCode)
    console.error('错误信息:', err.errMsg)
  }
})
```

**3. 样式问题**
```scss
// 问题：样式在不同平台表现不一致
// 解决方案：使用条件编译

.container {
  padding: 32rpx;
  
  // H5 特定样式
  /* #ifdef H5 */
  min-height: calc(100vh - 44px);
  /* #endif */
  
  // 小程序特定样式
  /* #ifdef MP */
  min-height: 100vh;
  /* #endif */
  
  // App 特定样式
  /* #ifdef APP-PLUS */
  padding-top: var(--status-bar-height);
  /* #endif */
}

// 问题：rpx 计算不准确
// 解决方案：注意设计稿基准
// 设计稿 750px -> 1rpx = 1px
// 设计稿 375px -> 1rpx = 0.5px
```

**4. 生命周期问题**
```javascript
// 问题：数据加载时机不对
// 解决方案：了解生命周期差异

export default {
  // 页面加载时触发（只触发一次）
  onLoad(options) {
    console.log('页面参数:', options)
    // 适合：初始化数据、获取路由参数
  },
  
  // 页面显示时触发（每次显示都触发）
  onShow() {
    console.log('页面显示')
    // 适合：刷新数据、更新状态
  },
  
  // 页面初次渲染完成（只触发一次）
  onReady() {
    console.log('页面渲染完成')
    // 适合：获取节点信息、设置导航栏
  }
}
```

#### 调试工具和技巧

**1. 控制台调试**
```javascript
// 条件编译调试信息
// #ifdef H5
console.log('H5环境调试信息')
// #endif

// #ifdef MP-WEIXIN
console.log('微信小程序调试信息')
// #endif

// 使用 uni.getSystemInfo 获取环境信息
uni.getSystemInfo({
  success: (res) => {
    console.log('平台信息:', {
      platform: res.platform,
      system: res.system,
      version: res.version,
      screenWidth: res.screenWidth,
      screenHeight: res.screenHeight
    })
  }
})
```

**2. 网络调试**
```javascript
// 请求拦截器（用于调试）
const originalRequest = uni.request
uni.request = function(options) {
  console.log('请求发起:', {
    url: options.url,
    method: options.method,
    data: options.data,
    header: options.header
  })
  
  const originalSuccess = options.success
  options.success = function(res) {
    console.log('请求响应:', {
      url: options.url,
      statusCode: res.statusCode,
      data: res.data
    })
    originalSuccess && originalSuccess(res)
  }
  
  const originalFail = options.fail
  options.fail = function(err) {
    console.error('请求失败:', {
      url: options.url,
      error: err
    })
    originalFail && originalFail(err)
  }
  
  return originalRequest.call(this, options)
}
```

**3. 性能调试**
```javascript
// 页面性能监控
export default {
  data() {
    return {
      startTime: 0
    }
  },
  
  onLoad() {
    this.startTime = Date.now()
  },
  
  onReady() {
    const loadTime = Date.now() - this.startTime
    console.log(`页面加载耗时: ${loadTime}ms`)
    
    // 上报性能数据
    if (loadTime > 2000) {
      console.warn('页面加载时间过长:', loadTime)
    }
  }
}

// 列表渲染性能优化
// 使用 key 优化渲染
// 避免在模板中使用复杂计算
// 使用 v-show 替代频繁的 v-if
```

**4. 错误监控**
```javascript
// App.vue 全局错误处理
export default {
  onError(err) {
    console.error('全局错误:', err)
    
    // 错误上报
    this.reportError(err)
  },
  
  onPageNotFound(res) {
    console.error('页面不存在:', res)
    
    // 重定向到首页或错误页
    uni.redirectTo({
      url: '/pages/index/index'
    })
  },
  
  methods: {
    reportError(err) {
      // 发送错误信息到监控平台
      uni.request({
        url: 'https://api.example.com/error-report',
        method: 'POST',
        data: {
          error: err.message,
          stack: err.stack,
          userAgent: navigator.userAgent,
          timestamp: Date.now()
        }
      })
    }
  }
}
```

#### 平台特定调试

**1. 微信小程序调试**
- 使用微信开发者工具的调试面板
- 检查 Console、Network、Storage 等标签
- 使用真机调试功能测试真实环境

**2. H5 调试**
- 使用浏览器开发者工具
- 检查移动端适配（响应式设计模式）
- 注意跨域问题和代理配置

**3. App 调试**
- 使用 HBuilderX 的真机运行功能
- 查看原生日志（Android Studio/Xcode）
- 测试原生能力（相机、位置、推送等）

#### 常用调试代码片段

**查看页面栈**
```javascript
const pages = getCurrentPages()
console.log('当前页面栈:', pages.map(page => page.route))
```

**获取节点信息**
```javascript
const query = uni.createSelectorQuery()
query.select('.my-element').boundingClientRect((rect) => {
  console.log('元素位置信息:', rect)
})
query.exec()
```

**检查存储数据**
```javascript
const storage = uni.getStorageInfoSync()
console.log('存储信息:', {
  keys: storage.keys,
  currentSize: storage.currentSize,
  limitSize: storage.limitSize
})
```### 调试和问题排查

#### 常见问题和解决方案

**1. 页面跳转问题**
```javascript
// 问题：页面跳转失败
// 原因：路径错误、页面未在 pages.json 中注册

// 解决方案：
// 1. 检查路径是否正确（以 / 开头）
uni.navigateTo({
  url: '/pages/order/detail?id=123'  // 正确
  // url: 'pages/order/detail'       // 错误：缺少前导斜杠
})

// 2. 确保页面已在 pages.json 中注册
{
  "pages": [
    {
      "path": "pages/order/detail",
      "style": {
        "navigationBarTitleText": "订单详情"
      }
    }
  ]
}

// 3. 检查跳转层级限制（小程序最多10层）
```

**2. 网络请求问题**
```javascript
// 问题：请求失败 fail statusCode:600
// 原因：域名未配置、SSL证书问题

// 调试方法：
// 1. 检查 manifest.json 中的域名配置
"h5": {
  "devServer": {
    "proxy": {
      "/api": {
        "target": "https://your-api.com",
        "changeOrigin": true
      }
    }
  }
}

// 2. 小程序开发时设置不校验域名
// 微信开发者工具 -> 设置 -> 项目设置 -> 不校验合法域名

// 3. 添加请求日志
uni.request({
  url: 'https://api.example.com/data',
  success: (res) => {
    console.log('请求成功:', res)
  },
  fail: (err) => {
    console.error('请求失败:', err)
    console.error('错误码:', err.statusCode)
    console.error('错误信息:', err.errMsg)
  }
})
```

**3. 样式问题**
```scss
// 问题：样式在不同平台表现不一致
// 解决方案：使用条件编译

.container {
  padding: 32rpx;
  
  // H5 特定样式
  /* #ifdef H5 */
  min-height: calc(100vh - 44px);
  /* #endif */
  
  // 小程序特定样式
  /* #ifdef MP */
  min-height: 100vh;
  /* #endif */
  
  // App 特定样式
  /* #ifdef APP-PLUS */
  padding-top: var(--status-bar-height);
  /* #endif */
}

// 问题：rpx 计算不准确
// 解决方案：注意设计稿基准
// 设计稿 750px -> 1rpx = 1px
// 设计稿 375px -> 1rpx = 0.5px
```

**4. 生命周期问题**
```javascript
// 问题：数据加载时机不对
// 解决方案：了解生命周期差异

export default {
  // 页面加载时触发（只触发一次）
  onLoad(options) {
    console.log('页面参数:', options)
    // 适合：初始化数据、获取路由参数
  },
  
  // 页面显示时触发（每次显示都触发）
  onShow() {
    console.log('页面显示')
    // 适合：刷新数据、更新状态
  },
  
  // 页面初次渲染完成（只触发一次）
  onReady() {
    console.log('页面渲染完成')
    // 适合：获取节点信息、设置导航栏
  }
}
```

#### 调试工具和技巧

**1. 控制台调试**
```javascript
// 条件编译调试信息
// #ifdef H5
console.log('H5环境调试信息')
// #endif

// #ifdef MP-WEIXIN
console.log('微信小程序调试信息')
// #endif

// 使用 uni.getSystemInfo 获取环境信息
uni.getSystemInfo({
  success: (res) => {
    console.log('平台信息:', {
      platform: res.platform,
      system: res.system,
      version: res.version,
      screenWidth: res.screenWidth,
      screenHeight: res.screenHeight
    })
  }
})
```

**2. 网络调试**
```javascript
// 请求拦截器（用于调试）
const originalRequest = uni.request
uni.request = function(options) {
  console.log('请求发起:', {
    url: options.url,
    method: options.method,
    data: options.data,
    header: options.header
  })
  
  const originalSuccess = options.success
  options.success = function(res) {
    console.log('请求响应:', {
      url: options.url,
      statusCode: res.statusCode,
      data: res.data
    })
    originalSuccess && originalSuccess(res)
  }
  
  const originalFail = options.fail
  options.fail = function(err) {
    console.error('请求失败:', {
      url: options.url,
      error: err
    })
    originalFail && originalFail(err)
  }
  
  return originalRequest.call(this, options)
}
```

**3. 性能调试**
```javascript
// 页面性能监控
export default {
  data() {
    return {
      startTime: 0
    }
  },
  
  onLoad() {
    this.startTime = Date.now()
  },
  
  onReady() {
    const loadTime = Date.now() - this.startTime
    console.log(`页面加载耗时: ${loadTime}ms`)
    
    // 上报性能数据
    if (loadTime > 2000) {
      console.warn('页面加载时间过长:', loadTime)
    }
  }
}

// 列表渲染性能优化
// 使用 key 优化渲染
// 避免在模板中使用复杂计算
// 使用 v-show 替代频繁的 v-if
```

**4. 错误监控**
```javascript
// App.vue 全局错误处理
export default {
  onError(err) {
    console.error('全局错误:', err)
    
    // 错误上报
    this.reportError(err)
  },
  
  onPageNotFound(res) {
    console.error('页面不存在:', res)
    
    // 重定向到首页或错误页
    uni.redirectTo({
      url: '/pages/index/index'
    })
  },
  
  methods: {
    reportError(err) {
      // 发送错误信息到监控平台
      uni.request({
        url: 'https://api.example.com/error-report',
        method: 'POST',
        data: {
          error: err.message,
          stack: err.stack,
          userAgent: navigator.userAgent,
          timestamp: Date.now()
        }
      })
    }
  }
}
```

#### 平台特定调试

**1. 微信小程序调试**
- 使用微信开发者工具的调试面板
- 检查 Console、Network、Storage 等标签
- 使用真机调试功能测试真实环境

**2. H5 调试**
- 使用浏览器开发者工具
- 检查移动端适配（响应式设计模式）
- 注意跨域问题和代理配置

**3. App 调试**
- 使用 HBuilderX 的真机运行功能
- 查看原生日志（Android Studio/Xcode）
- 测试原生能力（相机、位置、推送等）

#### 常用调试代码片段

**查看页面栈**
```javascript
const pages = getCurrentPages()
console.log('当前页面栈:', pages.map(page => page.route))
```

**获取节点信息**
```javascript
const query = uni.createSelectorQuery()
query.select('.my-element').boundingClientRect((rect) => {
  console.log('元素位置信息:', rect)
})
query.exec()
```

**检查存储数据**
```javascript
const storage = uni.getStorageInfoSync()
console.log('存储信息:', {
  keys: storage.keys,
  currentSize: storage.currentSize,
  limitSize: storage.limitSize
})
```