---
author: Peanut
created_at: 2026-04-07
purpose: 定义小程序开发工作流程，解决每次修改代码后需要重新登录的问题
---

# 小程序开发工作流程设计

## 问题背景

使用 VS Code + 微信开发者工具开发 uni-app 小程序时，每次修改代码后：
1. uni-app 自动重新编译到 `unpackage/dist/dev/mp-weixin`
2. 微信开发者工具检测到文件变化后自动重新加载
3. 小程序重启导致登录态丢失
4. 需要重新登录，严重影响开发效率

## 设计方案

采用 **H5 开发模式为主 + 微信开发者工具验证为辅** 的双轨工作流。

### 架构概览

```
┌─────────────────────────────────────────────────────────────┐
│                      开发工作流程                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐    代码修改    ┌─────────────────────┐     │
│  │   VS Code   │ ────────────> │   微信开发者工具     │     │
│  │  (编辑代码)  │               │   (预览/调试小程序)  │     │
│  └─────────────┘               └─────────────────────┘     │
│         │                              ▲                     │
│         │ npm run dev:h5               │                     │
│         ▼                              │                     │
│  ┌─────────────┐                      │                     │
│  │   浏览器     │ <────────────────────┘                     │
│  │ (H5 开发模式) │    大部分功能在此验证                        │
│  └─────────────┘                                            │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### 方案详情

#### 1. H5 开发模式（承担 90% 开发工作）

**启动命令**：
```bash
cd mini-program
npm run dev:h5
```

**访问地址**：`http://localhost:5173`（Vite 自动分配，如有占用自动递增）

**技术原理**：
- uni-app 的 H5 平台与小程序平台共享大部分代码
- 平台差异通过条件编译处理（`#ifdef H5` / `#ifdef MP-WEIXIN`）
- 登录态存储于浏览器 localStorage，页面刷新后保留

**适用场景**：
- UI/样式开发
- 业务逻辑开发
- 组件功能调试
- API 接口联调

**不适用场景**：
- 微信小程序特有 API（微信登录、分享、支付等）
- 小程序原生组件测试
- 真机兼容性验证

#### 2. 微信开发者工具配置优化

**配置步骤**：

1. 打开微信开发者工具
2. 菜单栏：**设置** → **通用设置**
3. 找到 **编译设置** 区域
4. **取消勾选** "文件修改后自动编译" 或 "保存后自动编译"

**效果**：
- VS Code 修改代码后，微信开发者工具不会自动重新编译
- 需要手动点击"编译"按钮（或 Ctrl+B）才会重新加载
- 减少不必要的重启，保持登录态

**替代方案**（如果上述选项不存在）：
- 在微信开发者工具中，勾选 "关闭真机调试自动刷新"
- 或使用 "预览" 模式而非 "编辑模式"

#### 3. 推荐工作流

| 开发阶段 | 使用环境 | 操作说明 |
|----------|----------|----------|
| UI/样式开发 | H5 | 快速迭代，即时预览 |
| 业务逻辑开发 | H5 | 大部分逻辑通用，使用浏览器 DevTools 调试 |
| 小程序 API 测试 | 小程序 | 如微信登录、分享等特有功能 |
| 最终验证 | 小程序 | 发布前在真机环境测试 |

**日常开发流程**：

```bash
# 1. 启动 H5 开发服务器（终端 1）
cd mini-program
npm run dev:h5

# 2. 打开浏览器访问 http://localhost:5173
# 3. 登录一次后，后续刷新页面登录态保留

# 4. 需要测试小程序特性时：
#    - 在另一个终端启动小程序模式
npm run dev:mp-weixin
#    - 在微信开发者工具中打开 unpackage/dist/dev/mp-weixin
#    - 手动触发编译（避免自动刷新）
```

## 技术细节

### uni-app 平台差异处理

**条件编译语法**：

```javascript
// #ifdef H5
// H5 平台特有代码
// #endif

// #ifdef MP-WEIXIN
// 微信小程序平台特有代码
// #endif

// #ifdef H5 || MP-WEIXIN
// 多平台通用代码
// #endif
```

**CSS 条件编译**：

```css
/* #ifdef H5 */
.h5-only-style {
  /* H5 特有样式 */
}
/* #endif */
```

### 登录态持久化

当前项目已正确实现登录态存储：

```javascript
// 存储 token
uni.setStorageSync('access_token', token)

// 读取 token
const token = uni.getStorageSync('access_token')

// 删除 token（登出）
uni.removeStorageSync('access_token')
```

**注意**：uni-app 的 storage API 在不同平台使用不同的底层存储：
- H5：localStorage
- 微信小程序：wx.setStorageSync
- 其他小程序：对应平台的 storage API

### 端口管理

H5 开发服务器默认端口为 5173，如被占用会自动递增（5174、5175...）。

**检查端口占用**：
```bash
netstat -ano | findstr "5173"
```

**终止占用进程**：
```bash
taskkill /F /PID <进程 ID>
```

## 注意事项

### 1. H5 与小程序的差异

| 特性 | H5 | 小程序 |
|------|-----|--------|
| 路由 | vue-router | 小程序页面栈 |
| 存储 | localStorage | wx.storage |
| 网络 | XMLHttpRequest | wx.request |
| 登录 | 自定义登录 | 微信登录 |
| 分享 | 浏览器分享 | 微信分享 API |

### 2. 需要小程序环境验证的功能

- 微信小程序登录
- 微信分享
- 微信支付
- 小程序码生成
- 微信开放标签
- 真机兼容性

### 3. 开发效率优化建议

1. **使用浏览器 DevTools**：
   - Chrome DevTools 的 Elements 面板检查样式
   - Network 面板查看 API 请求
   - Console 面板调试 JavaScript
   - Application 面板查看 localStorage

2. **H5 热更新**：
   - 修改样式后自动刷新
   - 修改逻辑后热替换（保持应用状态）

3. **小程序模式仅用于验证**：
   - 不要在小菜模式中进行日常开发
   - 只在需要测试小程序特有功能时切换

## 验收标准

采用此工作流程后应达到：

- [x] 日常开发无需频繁重新登录
- [x] H5 模式下可完成 90% 的开发工作
- [x] 小程序模式仅用于最终验证
- [x] 开发效率显著提升

## 参考文档

- [uni-app 条件编译](https://uniapp.dcloud.net.cn/tutorial/platform.html)
- [uni-app H5 开发模式](https://uniapp.dcloud.net.cn/quickstart-h5.html)
- [微信开发者工具设置](https://developers.weixin.qq.com/miniprogram/dev/devtools/projectconfig.html)