docs: 创建小程序体验版诊断日志设计文档

- 添加 env.js 环境配置解析日志 - 添加 request.js HTTP 请求/响应日志 - 定义预期输出和验证步骤 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-18 22:43:00 +08:00
parent fef29e7b0a
commit 4bf3899a76
1 changed files with 208 additions and 0 deletions
@@ -0,0 +1,208 @@
+---
+author: peanu
+created_at: 2026-03-18
+purpose: 设计小程序体验版接口诊断日志方案，定位体验版无法调用接口的问题
+---
+
+# 小程序体验版诊断日志设计文档
+
+## 问题描述
+
+体验版小程序上传到微信后台后，用户在使用时无法调用后端接口，需要添加日志来诊断问题根源。
+
+## 目标
+
+通过在关键位置添加日志，确认以下信息：
+1. 环境变量是否正确注入到编译产物中
+2. 当前运行的是什么环境（dev/test/prod）
+3. 解析出的 API_BASE_URL 是否正确（HTTPS 域名 vs HTTP IP）
+4. 请求的完整 URL 是什么
+5. 请求是否成功，失败的具体错误信息是什么
+
+## 设计方案
+
+### 修改文件清单
+
+| 文件 | 修改类型 | 目的 |
+|------|---------|------|
+| `mini-program/src/config/env.js` | 修改 | 添加环境变量解析日志 |
+| `mini-program/src/services/request.js` | 修改 | 添加 HTTP 请求/响应日志 |
+
+### 第一部分：env.js 日志
+
+**位置**: `getConfig()` 函数末尾
+
+**添加代码**:
+```javascript
+const getConfig = () => {
+  const base = envConfig[currentEnv] || envConfig[ENV_TYPE.DEV]
+  const apiBaseUrl = import.meta.env.VITE_API_BASE_URL || base.API_BASE_URL
+  const wsUrl = import.meta.env.VITE_WS_URL || base.WS_URL
+  const debug = import.meta.env.VITE_DEBUG !== undefined
+    ? import.meta.env.VITE_DEBUG === 'true'
+    : base.DEBUG
+
+  // 添加诊断日志
+  if (debug) {
+    console.log('[ENV] 环境配置:', {
+      rawEnv: import.meta.env.VITE_APP_ENV,
+      normalizedEnv: currentEnv,
+      API_BASE_URL: apiBaseUrl,
+      WS_URL: wsUrl,
+      DEBUG: debug,
+      isFromEnvFile: import.meta.env.VITE_API_BASE_URL ? 'yes' : 'fallback-to-config'
+    })
+  }
+
+  return {
+    API_BASE_URL: apiBaseUrl,
+    WS_URL: wsUrl,
+    DEBUG: debug
+  }
+}
+```
+
+**预期输出（测试环境正常情况）**:
+```
+[ENV] 环境配置：{
+  rawEnv: "test",
+  normalizedEnv: "test",
+  API_BASE_URL: "https://lifescript.happylifeos.com/api",
+  WS_URL: "wss://lifescript.happylifeos.com/ws",
+  DEBUG: true,
+  isFromEnvFile: "yes"
+}
+```
+
+**预期输出（回退到默认配置）**:
+```
+[ENV] 环境配置：{
+  rawEnv: "test",
+  normalizedEnv: "test",
+  API_BASE_URL: "http://101.200.208.45:19089/api",  ← 注意这是 HTTP 不是 HTTPS
+  WS_URL: "ws://101.200.208.45:19089",
+  DEBUG: true,
+  isFromEnvFile: "fallback-to-config"  ← 说明.env.test 未生效
+}
+```
+
+### 第二部分：request.js 日志
+
+**位置**: `request()` 函数、`success` 回调、`fail` 回调
+
+**添加代码**:
+```javascript
+const request = (options) => {
+  const debug = getEnvValue('DEBUG')
+  const fullUrl = `${API_BASE_URL}${options.url}`
+
+  // 请求日志
+  if (debug) {
+    console.log('[API Request]', {
+      method: options.method || 'GET',
+      url: fullUrl,
+      path: options.url,
+      env: import.meta.env.VITE_APP_ENV
+    })
+  }
+
+  return new Promise((resolve, reject) => {
+    uni.request({
+      url: fullUrl,
+      method: options.method || 'GET',
+      data: options.data,
+      header: getHeaders(),
+      timeout: 30000,
+      success: (res) => {
+        const { data, statusCode } = res
+
+        // 响应日志
+        if (debug) {
+          console.log('[API Response]', {
+            path: options.url,
+            status: statusCode,
+            code: data?.code,
+            success: data?.code === 200 || data?.code === 0
+          })
+        }
+
+        // 处理 401 未授权
+        if (statusCode === 401) {
+          uni.removeStorageSync('access_token')
+          uni.removeStorageSync('refresh_token')
+          uni.redirectTo({ url: '/pages/login/index' })
+          reject(new Error('登录已过期，请重新登录'))
+          return
+        }
+
+        // 后端返回格式：{ code, message, data }
+        if (data.code === 200 || data.code === 0) {
+          resolve(data)
+        } else {
+          reject(new Error(data.message || '请求失败'))
+        }
+      },
+      fail: (err) => {
+        // 错误日志
+        if (debug) {
+          console.error('[API Error]', {
+            path: options.url,
+            error: err.errMsg,
+            env: import.meta.env.VITE_APP_ENV
+          })
+        }
+        reject(new Error(err.errMsg || '网络错误'))
+      }
+    })
+  })
+}
+```
+
+**预期输出（成功请求）**:
+```
+[API Request] {
+  method: "GET",
+  url: "https://lifescript.happylifeos.com/api/auth/sms-code",
+  path: "/auth/sms-code",
+  env: "test"
+}
+[API Response] {
+  path: "/auth/sms-code",
+  status: 200,
+  code: 200,
+  success: true
+}
+```
+
+**预期输出（连接失败）**:
+```
+[API Request] { ... }
+[API Error] {
+  path: "/auth/sms-code",
+  error: "timeout",  ← 或其他错误信息
+  env: "test"
+}
+```
+
+## 验证步骤
+
+1. **编译体验版**: `npm run build:mp-weixin:test`
+2. **微信开发者工具导入**: `unpackage/dist/test/mp-weixin`
+3. **打开调试面板**: 查看 Console 输出
+4. **触发登录请求**: 输入手机号，点击"获取验证码"
+5. **检查日志输出**: 确认 API_BASE_URL 是 HTTPS 域名还是 HTTP IP
+
+## 成功标准
+
+- [ ] env.js 日志显示 `API_BASE_URL` 为 `https://lifescript.happylifeos.com/api`
+- [ ] request.js 日志显示完整请求 URL 以 `https://`开头
+- [ ] 请求能够成功收到服务器响应（非 ERR_CONNECTION_CLOSED）
+- [ ] 日志只在 DEBUG=true 时打印（测试/开发环境）
+
+## 后续诊断方向
+
+根据日志输出结果判断：
+
+1. **如果 API_BASE_URL 是 HTTP IP 而非 HTTPS 域名** → .env.test 文件未正确注入，需要检查构建配置
+2. **如果 API_BASE_URL 正确但仍连接失败** → 可能是微信域名白名单配置问题或 SSL 证书问题
+3. **如果根本没有日志输出** → DEBUG 标志未正确设置或编译模式不对