peanut
2008d996e6
定义 H5 开发模式 + 微信开发者工具验证的双轨工作流: - 日常开发使用 H5 模式 (npm run dev:h5)，登录态保留 - 小程序特性测试使用微信开发者工具 - 配置微信开发者工具关闭自动编译 解决 issues: 每次代码修改后需要重新登录小程序的问题
230 lines
7.1 KiB
Markdown
230 lines
7.1 KiB
Markdown
---
|
||
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)
|