happy-life-star/docs/superpowers/specs/2026-04-07-mini-program-dev-workflow-design.md

author, created_at, purpose

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

小程序开发工作流程设计

问题背景

使用 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% 开发工作）

启动命令：

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 测试	小程序	如微信登录、分享等特有功能
最终验证	小程序	发布前在真机环境测试

日常开发流程：

# 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 平台差异处理

条件编译语法：

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

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

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

CSS 条件编译：

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

登录态持久化

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

// 存储 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...）。

检查端口占用：

netstat -ano | findstr "5173"

终止占用进程：

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. 小程序模式仅用于验证：

   • 不要在小菜模式中进行日常开发
   • 只在需要测试小程序特有功能时切换

验收标准

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

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

参考文档

• uni-app 条件编译
• uni-app H5 开发模式
• 微信开发者工具设置