163 lines
4.9 KiB
Markdown
163 lines
4.9 KiB
Markdown
# 前端 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` 已修改，使用自动探测逻辑 |