docs: 添加小程序开发工作流程设计文档
定义 H5 开发模式 + 微信开发者工具验证的双轨工作流: - 日常开发使用 H5 模式 (npm run dev:h5)，登录态保留 - 小程序特性测试使用微信开发者工具 - 配置微信开发者工具关闭自动编译 解决 issues: 每次代码修改后需要重新登录小程序的问题
This commit is contained in:
@@ -0,0 +1,229 @@
|
||||
---
|
||||
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)
|
||||
Reference in New Issue
Block a user