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:
@@ -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)
|
||||
Reference in New Issue
Block a user