feat(mini-program): 添加 H5 开发工作流支持

实施内容:
- 创建 start-h5-dev.bat 快捷启动脚本
- 更新 CLAUDE.md 添加 H5 开发模式说明
- 创建微信开发者工具配置指南

配套文档:
- docs/superpowers/specs/2026-04-07-mini-program-dev-workflow-design.md (设计文档)
- docs/superpowers/guides/2026-04-07-wechat-devtools-config.md (配置指南)

解决 issues: 每次代码修改后需要重新登录小程序的问题
工作流:H5 模式日常开发 + 小程序模式最终验证
This commit is contained in:
2026-04-07 21:12:46 +08:00
parent 2008d996e6
commit e2b41f23b0
3 changed files with 208 additions and 0 deletions
+19
View File
@@ -125,6 +125,25 @@ npm run dev:h5
npm run build:h5 npm run build:h5
``` ```
### mini-program(推荐开发模式)
**H5 开发模式**(日常开发,推荐):
```bash
cd mini-program
# 或使用启动脚本
start-h5-dev.bat
```
访问 `http://localhost:5173`,登录态保留,支持热更新。
**微信小程序开发模式**(仅用于小程序特性验证):
```bash
cd mini-program
npm run dev:mp-weixin
```
在微信开发者工具中打开 `unpackage/dist/dev/mp-weixin`
**开发工作流说明**:详见 [小程序开发工作流程设计](docs/superpowers/specs/2026-04-07-mini-program-dev-workflow-design.md)
### 一键部署 ### 一键部署
```bash ```bash
@@ -0,0 +1,170 @@
---
author: Peanut
created_at: 2026-04-07
purpose: 提供微信开发者工具的配置指南,优化小程序开发体验
---
# 微信开发者工具配置指南
## 问题背景
微信开发者工具默认会在检测到项目文件变化时自动重新编译,这导致:
1. 小程序自动重新加载
2. 登录态丢失
3. 需要重新登录,影响开发效率
## 配置步骤
### 步骤 1:打开设置面板
1. 打开 **微信开发者工具**
2. 在顶部菜单栏选择:
- **Windows**: `设置``通用设置`
- 或使用快捷键 `Ctrl + ,`
### 步骤 2:关闭自动编译
**通用设置** 面板中:
1. 找到 **编译设置** 区域
2. **取消勾选** 以下选项(如果存在):
- [ ] 文件修改后自动编译
- [ ] 保存后自动刷新
- [ ] 监听文件变化自动更新
### 步骤 3:配置项目设置
**项目设置** 中:
1. 找到你的项目 `emotion-museun/mini-program`
2. 确认 **项目路径** 指向:`unpackage/dist/dev/mp-weixin`
3. 关闭 **自动预览** 功能
## 手动编译方式
关闭自动编译后,需要手动触发编译:
| 操作 | 方式 |
|------|------|
| 编译 | 点击工具栏 **编译** 按钮 |
| 快捷键 | `Ctrl + B` (Windows) |
| 清缓存并编译 | `工具``清除缓存``清除全部`,然后编译 |
## 推荐工作流
### 日常开发(H5 模式)
```bash
cd mini-program
# 双击运行 start-h5-dev.bat
# 或手动执行
npm run dev:h5
```
在浏览器(Chrome/Edge)中访问 `http://localhost:5173` 进行开发。
### 小程序特性验证
当需要测试小程序特有功能时:
1. **启动小程序编译模式**
```bash
cd mini-program
npm run dev:mp-weixin
```
2. **在微信开发者工具中**
- 导入项目目录:`unpackage/dist/dev/mp-weixin`
- 手动点击 **编译** 按钮
3. **验证小程序特有功能**
- 微信登录
- 微信分享
- 小程序支付
- 其他小程序特有 API
## 常见问题
### Q1: 关闭自动编译后看不到代码变化
**解决方案**
1. 确保 uni-app 开发服务器正在运行
2. 在微信开发者工具中手动点击 **编译** 按钮
3. 如有必要,先清除缓存再编译
### Q2: 登录态仍然丢失
**可能原因**
- 微信开发者工具清除了 storage
- 小程序重新初始化导致
**解决方案**
1. 在微信开发者工具中,勾选 **调试器** → **Storage**,检查 token 是否存在
2. 如果 token 被清除,说明是工具行为,建议改用 H5 模式开发
3. 或在代码中添加登录态自动恢复逻辑
### Q3: H5 模式与小程序模式显示不一致
**原因**
- 平台差异导致(H5 使用浏览器渲染,小程序使用原生渲染)
- 某些样式或 API 在不同平台表现不同
**解决方案**
1. 优先在 H5 模式完成开发
2. 切换到小程序模式进行最终验证
3. 使用条件编译处理平台差异:
```javascript
// #ifdef H5
// H5 特有代码
// #endif
// #ifdef MP-WEIXIN
// 小程序特有代码
// #endif
```
## 最佳实践
### 1. 双环境开发
| 开发阶段 | 使用环境 | 说明 |
|----------|----------|------|
| UI/样式 | H5 | 快速迭代,即时预览 |
| 业务逻辑 | H5 | 使用浏览器 DevTools 调试 |
| 小程序 API | 小程序 | 微信登录、分享等 |
| 最终验证 | 小程序 | 发布前测试 |
### 2. 登录态持久化
当前项目已实现登录态存储:
```javascript
// 存储 token
uni.setStorageSync('access_token', token)
// 读取 token
const token = uni.getStorageSync('access_token')
```
### 3. 效率优化建议
1. **使用浏览器 DevTools**
- Chrome DevTools 检查元素
- Network 面板查看 API 请求
- Console 面板调试
- Application 面板查看 storage
2. **减少小程序模式切换**
- 90% 的开发在 H5 模式完成
- 只在必要时切换到小程序模式
3. **使用快捷启动脚本**
- `start-h5-dev.bat` 一键启动 H5 开发
- 自动打开浏览器
## 参考链接
- [微信开发者工具官方文档](https://developers.weixin.qq.com/miniprogram/dev/devtools/devtools.html)
- [uni-app 条件编译](https://uniapp.dcloud.net.cn/tutorial/platform.html)
- [小程序开发工作流程设计](docs/superpowers/specs/2026-04-07-mini-program-dev-workflow-design.md)
+19
View File
@@ -0,0 +1,19 @@
@echo off
chcp 65001 >nul
echo.
echo =====================================
echo Life OS - H5 开发模式启动
echo =====================================
echo.
echo 正在启动 H5 开发服务器...
echo.
echo 访问地址:http://localhost:5173 (如被占用自动递增)
echo.
echo 按 Ctrl+C 可停止服务
echo.
echo =====================================
echo.
cd /d "%~dp0\mini-program"
npm run dev:h5