topfans/docs/api-base-url-switch-plan.md

前端 API Base URL 自动切换方案

背景

前端 api.js 中的 baseURL 目前是硬编码，需要根据后端运行环境手动切换。为了实现自动化，制定以下方案。

项目说明：uniapp 移动端应用，使用 HBuilderX "运行在真机调试"进行开发调试，打包时使用生产环境地址。

---

方案一：DEBUG_MODE 开关（手动切换）

在 api.js 顶部添加一个开关，真机调试时用开发地址，打包前改成生产地址：

const DEBUG_MODE = true  // 真机调试时 true，打包前改成 false

const DEV_BASE = 'http://192.168.110.60:8080'    // 开发环境
const PROD_BASE = 'http://101.132.250.62:8080'   // 生产环境

const baseURL = DEBUG_MODE ? DEV_BASE : PROD_BASE

优点

优点	说明
简单直接	只需改一个布尔值
零学习成本	一眼看出当前用哪个地址

缺点

缺点	说明
手动切换	打包前需记得手动改值

---

方案二：自动探测后端可用性（推荐 - 全自动）

实现方式

启动时自动探测开发环境是否可用，能连通则用开发地址，否则用生产地址：

const DEV_BASE = 'http://192.168.110.60:8080'    // 开发环境
const PROD_BASE = 'http://101.132.250.62:8080'   // 生产环境

let baseURL = PROD_BASE  // 默认生产

// 启动时探测开发环境是否可用
uni.request({
    url: DEV_BASE + '/api/v1/health',
    method: 'GET',
    timeout: 2000,
    success: (res) => {
        if (res.statusCode === 200) {
            baseURL = DEV_BASE  // 开发环境可用，用开发
        }
    },
    fail: () => {
        // 开发环境不可用，保持生产地址
    }
})

原理：启动时先尝试连接开发服务器 192.168.110.60:8080，能连通就用开发地址，连不通自动用生产地址。

优点

优点	说明
全自动	无论调试还是打包都自动选择正确地址
零手动操作	不需要记得改任何开关
适合移动端	开发时手机和电脑同网络，能探测到；生产打包后手机连不上开发地址，自动用生产

缺点

缺点	说明
启动多一步	首次启动会探测一次（2秒超时）
依赖后端	需要后端有 /api/v1/health 接口（或任意能响应的接口）

工作流程

场景	探测结果	使用的地址
真机调试（手机和电脑同局域网）	192.168.110.60 能连通	http://192.168.110.60:8080（开发）
打包 App（手机连接外网）	192.168.110.60 连不通	http://101.132.250.62:8080（生产）

后端要求

后端需要有一个能响应 HTTP 200 的健康检查接口。常见选择：

• 已有接口：如果后端有 /health 或类似接口，直接使用
• 新建接口：在 gateway 添加一个简单的健康检查接口
• 复用接口：用现有的任意接口（如 /api/v1/auth/me，但需要 token，可能不适合）

如果你后端没有现成的健康检查接口，我可以帮你设计一个简单的实现方案。

---

方案三：uniapp 条件编译（不推荐）

// #ifdef APP-PLUS
const baseURL = 'http://101.132.250.62:8080'  // App 打包生产环境
// #endif

// #ifdef H5
const baseURL = 'http://192.168.110.60:8080'  // H5 开发环境
// #endif

问题：HBuilderX 真机调试默认走 APP-PLUS 条件，调试时也会用生产地址，不适合。

---

方案四：Vite 环境变量（不推荐）

const baseURL = import.meta.env.VITE_API_BASE_URL || 'http://192.168.110.60:8080'

问题：uniapp HBuilderX 不走 Vite 的 dev/build 命令，环境变量不会自动切换。

---

总结对比

对比项	方案一（开关）	方案二（自动探测）	条件编译	Vite 环境变量
自动化程度	❌ 手动	✅ 全自动	❌ 手动	❌ 手动
uniapp 兼容	✅	✅	❌ 不适合调试	❌ 不支持
简单程度	✅ 最简单	中等	中等	中等
适合真机调试	✅	✅	❌ 否	❌ 否
推荐指数	⭐⭐	⭐⭐⭐	⭐	⭐

---

地址确认

环境	地址
开发环境	http://192.168.110.60:8080
生产环境	http://101.132.250.62:8080

---

确认事项

1. 选择方案：___
2. 开发环境地址：http://192.168.110.60:8080
3. 生产环境地址：http://101.132.250.62:8080
4. 后端是否有健康检查接口：___（如有请告知路径）

---

实施记录

• ✅ 方案二已实施（自动探测后端可用性）
• ✅ 后端 /health 接口确认存在
• ✅ api.js 已修改，使用自动探测逻辑