# miniprogram-web

**Repository Path**: alamhubb/miniprogram-web

## Basic Information

- **Project Name**: miniprogram-web
- **Description**: 让浏览器环境支持运行原生的微信小程序代码
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-27
- **Last Updated**: 2026-01-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MiniApp H5 Runtime

在浏览器中运行微信小程序

## 🎯 项目目标

使原生微信小程序能够在浏览器中运行，用于开发调试和演示。

## 📦 包结构

```
miniprogram-h5/
├── miniprogram-runtime/     # 核心运行时（处理原生小程序）
├── miniprogram-compiler/    # WXML/WXSS 编译器
├── miniprogram-uniapp/      # UniApp 兼容层（可选）
├── vite-plugin-mp/      # Vite 插件
└── only-my/             # 示例项目
```

## 🏗️ 架构设计

### 核心原则

1. **依赖 uni-h5**：复用 uni-h5 的 API、路由、生命周期系统
2. **单向依赖**：miniprogram-uniapp → miniprogram-runtime
3. **原生优先**：专注于原生小程序支持

### 依赖关系图

```
┌─────────────────────────────────────────────────────────────┐
│                      用户小程序代码                           │
│         Page({ data, onLoad })   Component()                 │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                    miniprogram-runtime                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐           │
│  │ platform.ts │  │page-loader  │  │component-   │           │
│  │ Page/App/   │  │loadMiniPage │  │loader.ts    │           │
│  │ Component   │  │             │  │             │           │
│  └─────────────┘  └─────────────┘  └─────────────┘           │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                      @dcloudio/uni-h5                         │
│  - wx/uni API 实现                                           │
│  - 路由系统（vue-router）                                     │
│  - LayoutComponent                                           │
│  - 生命周期钩子                                               │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                          Vue 3                                │
└─────────────────────────────────────────────────────────────┘
```

## 🚀 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. Vite 配置

```typescript
// vite.config.ts
import { vitePluginMp } from 'vite-plugin-mp'

export default defineConfig({
  plugins: [
    ...vitePluginMp({
      mpDist: 'dist/miniprogram',  // 小程序编译产物目录
    })
  ]
})
```

### 3. 入口文件

```typescript
// main.ts
import { start } from 'miniprogram-runtime'

start({
  mpDist: 'dist/miniprogram'
})
```

### 4. 运行

```bash
npm run dev
```

## 🔧 核心模块说明

### miniprogram-runtime

核心运行时，提供：

- **platform.ts**：全局 `wx`、`uni`、`Page()`、`App()`、`Component()` 函数
- **component-loader.ts**：创建小程序实例（data + setData）、包装为 Vue 组件
- **page-loader.ts**：加载页面、使用 uni-app 生命周期钩子
- **router.ts**：配置 `__uniRoutes` 供 uni-h5 使用
- **app-starter.ts**：应用启动流程

### 生命周期系统

**Page 生命周期**：使用 `@dcloudio/uni-app` 的钩子
```typescript
import { onLoad, onShow, onReady } from '@dcloudio/uni-app'

// Page({ onLoad }) → onLoad(() => config.onLoad.call(context))
```

**Component 生命周期**：映射到 Vue 钩子
```
created → 同步执行
attached → onBeforeMount
ready → onMounted
detached → onUnmounted
```

### 数据响应式

```javascript
// 小程序代码
Page({
  data: { count: 0 },
  increment() {
    this.setData({ count: this.data.count + 1 })
  }
})
```

`this.data` 是 Vue `reactive` 对象，`setData` 直接修改它，自动触发视图更新。

## 📚 各包详细文档

| 包名 | 说明 |
|------|------|
| [miniprogram-runtime](./miniprogram-runtime/README.md) | 核心运行时 |
| [vite-plugin-mp](./vite-plugin-mp/README.md) | Vite 插件 |
| [miniprogram-compiler](./miniprogram-compiler/README.md) | WXML/WXSS 编译器 |

## 🔄 运行流程

```
1. Vite 启动 → vite-plugin-mp 配置环境
   ↓
2. 加载入口 → miniprogram-runtime.start()
   ↓
3. 读取 app.json → 获取页面列表
   ↓
4. setupUniRoutes() → 配置 __uniRoutes
   ↓
5. 加载 app.js → 触发 App()
   ↓
6. setupApp() 包装根组件
   ↓
7. createApp() + uni-h5 plugin
   ↓
8. app.mount('#app')
   ↓
9. 路由匹配 → loadMiniPage()
   ↓
10. 加载 .js/.wxml/.wxss → Page()
    ↓
11. createMiniInstance() → miniInstanceToVue()
    ↓
12. 触发 onLoad/onShow/onReady → 渲染页面
```

## 🛠️ 调试技巧

```javascript
// 查看路由配置
console.log(window.__uniRoutes)

// 查看页面栈
console.log(window.getCurrentPages())

// 查看 App 实例
console.log(window.getApp())

// 查看全局配置
console.log(window.__uniConfig)
```

## 🐛 常见问题

### Q: `__UNI_FEATURE_xxx is not defined`

**原因**：缺少全局标志

**解决**：在 `uni-h5-config.ts` 中添加：
```typescript
;(window as any).__UNI_FEATURE_XXX__ = false
```

### Q: `UniServiceJSBridge is not defined`

**原因**：uni-h5 内部需要全局 Bridge

**解决**：在 `platform.ts` 中添加：
```typescript
;(window as any).UniServiceJSBridge = (uniH5 as any).UniServiceJSBridge
```

### Q: 页面不显示

**检查**：
1. `__uniRoutes` 是否正确配置
2. 页面路径是否正确
3. Console 是否有错误

## 📄 许可证

MIT