---
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)
