# 前端 API Base URL 自动切换方案

## 背景

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

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

---

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

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

```javascript
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
```

### 优点

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

### 缺点

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

---

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

### 实现方式

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

```javascript
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 条件编译（不推荐）

```javascript
// #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 环境变量（不推荐）

```javascript
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. **后端是否有健康检查接口**：___（如有请告知路径）

---

## 实施记录

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