258 lines
7.4 KiB
Markdown
258 lines
7.4 KiB
Markdown
# 人生 OS 微信小程序
|
||
|
||
基于 UniApp + Vue 3 的人生 OS 微信小程序，与 Web 端（life-script）共享后端 API。
|
||
|
||
## 技术栈
|
||
|
||
- **框架**: UniApp
|
||
- **语言**: Vue 3 + TypeScript
|
||
- **状态管理**: Pinia
|
||
- **HTTP 请求**: uni.request 封装
|
||
|
||
## 快速开始
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
cd mini-program
|
||
npm install
|
||
# 或使用 pnpm
|
||
pnpm install
|
||
```
|
||
|
||
### 2. 开发模式
|
||
|
||
#### 微信小程序开发预览
|
||
|
||
```bash
|
||
# 启动微信小程序开发服务器
|
||
npm run dev:mp-weixin
|
||
# 或
|
||
pnpm dev:mp-weixin
|
||
```
|
||
|
||
启动后，打开**微信开发者工具**：
|
||
1. 导入项目目录：`mini-program/unpackage/dist/dev/mp-weixin`
|
||
2. 在开发者工具中可以实时预览和调试
|
||
|
||
#### H5 开发预览
|
||
|
||
```bash
|
||
# 启动 H5 开发服务器
|
||
npm run dev:h5
|
||
# 或
|
||
pnpm dev:h5
|
||
```
|
||
|
||
启动后，在浏览器访问：`http://localhost:5173`
|
||
|
||
### 3. 编译打包
|
||
|
||
#### 编译为微信小程序（生产环境/正式版）
|
||
|
||
```bash
|
||
# 生产环境编译（调用服务器 API，DEBUG=false）
|
||
npm run build:mp-weixin
|
||
# 或
|
||
pnpm build:mp-weixin
|
||
```
|
||
|
||
编译输出目录：`unpackage/dist/build/mp-weixin`
|
||
|
||
**说明**：此命令用于编译正式版小程序，使用生产环境配置，调用服务器 API。
|
||
|
||
#### 编译为微信小程序（测试环境/体验版）
|
||
|
||
```bash
|
||
# 测试环境编译（调用服务器 API，DEBUG=true）
|
||
npm run build:mp-weixin:test
|
||
# 或
|
||
pnpm build:mp-weixin:test
|
||
```
|
||
|
||
编译输出目录：`unpackage/dist/test/mp-weixin`
|
||
|
||
**说明**：此命令用于编译体验版小程序，使用测试环境配置，调用服务器 API 但保留 DEBUG 模式便于调试。
|
||
|
||
**部署步骤**：
|
||
1. 打开微信开发者工具
|
||
2. 导入目录：`mini-program/unpackage/dist/build/mp-weixin`
|
||
3. 点击「上传」按钮，上传代码到微信公众平台
|
||
4. 登录微信公众平台进行版本提交和发布
|
||
|
||
#### 编译为 H5
|
||
|
||
```bash
|
||
# 生产环境编译
|
||
npm run build:h5
|
||
# 或
|
||
pnpm build:h5
|
||
```
|
||
|
||
编译输出目录：`unpackage/dist/build/h5`
|
||
|
||
### 4. 环境配置
|
||
|
||
项目使用 `.env` 文件管理环境变量：
|
||
|
||
| 文件 | 说明 | API 地址 | WebSocket 地址 |
|
||
|------|------|----------|----------------|
|
||
| `.env.development` | 开发环境配置 | https://lifescript.happylifeos.com/api | wss://lifescript.happylifeos.com/ws |
|
||
| `.env.test` | 测试环境配置 | https://lifescript.happylifeos.com/api | wss://lifescript.happylifeos.com/ws |
|
||
| `.env.production` | 生产环境配置 | https://lifescript.happylifeos.com/api | wss://lifescript.happylifeos.com/ws |
|
||
|
||
**开发环境配置**（`.env.development`）：
|
||
```bash
|
||
# 开发环境配置（本地开发调试）
|
||
VITE_APP_ENV=dev
|
||
VITE_API_BASE_URL=https://lifescript.happylifeos.com/api
|
||
VITE_WS_URL=wss://lifescript.happylifeos.com/ws
|
||
VITE_DEBUG=true
|
||
```
|
||
|
||
**测试环境配置**（`.env.test`）：
|
||
```bash
|
||
# 测试环境配置（小程序体验版）
|
||
VITE_APP_ENV=test
|
||
VITE_API_BASE_URL=https://lifescript.happylifeos.com/api
|
||
VITE_WS_URL=wss://lifescript.happylifeos.com/ws
|
||
VITE_DEBUG=true
|
||
```
|
||
|
||
**生产环境配置**（`.env.production`）：
|
||
```bash
|
||
# 生产环境配置（小程序正式版）
|
||
VITE_APP_ENV=prod
|
||
VITE_API_BASE_URL=https://lifescript.happylifeos.com/api
|
||
VITE_WS_URL=wss://lifescript.happylifeos.com/ws
|
||
VITE_DEBUG=false
|
||
```
|
||
|
||
**环境选择指南**：
|
||
- **本地开发**：使用 `npm run dev:mp-weixin`，自动加载开发环境配置
|
||
- **体验版发布**：使用 `npm run build:mp-weixin:test`，使用测试环境配置（服务器 API + DEBUG 模式）
|
||
- **正式版发布**：使用 `npm run build:mp-weixin`，使用生产环境配置（服务器 API + 关闭 DEBUG）
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
mini-program/
|
||
├── src/
|
||
│ ├── pages/ # 页面目录
|
||
│ │ ├── splash/ # 启动页
|
||
│ │ ├── login/ # 登录页
|
||
│ │ ├── onboarding/ # 引导页
|
||
│ │ ├── main/ # 主页容器
|
||
│ │ │ ├── index.vue # 主页面
|
||
│ │ │ ├── RecordView.vue # 记录页
|
||
│ │ │ ├── ScriptView.vue # 剧本页
|
||
│ │ │ └── PathView.vue # 路径页
|
||
│ │ └── profile/ # 个人页
|
||
│ ├── components/ # 公共组件
|
||
│ │ └── MusicPlayer.vue # 音乐播放器
|
||
│ ├── services/ # API 服务层
|
||
│ │ ├── request.js # 请求封装
|
||
│ │ ├── auth.js # 认证服务
|
||
│ │ ├── userProfile.js # 用户档案服务
|
||
│ │ ├── lifeEvent.js # 生命事件服务
|
||
│ │ ├── epicScript.js # 剧本服务
|
||
│ │ └── lifePath.js # 路径服务
|
||
│ ├── stores/ # 状态管理
|
||
│ │ └── app.js # 应用状态
|
||
│ ├── config/ # 配置文件
|
||
│ │ └── env.js # 环境配置
|
||
│ ├── static/ # 静态资源
|
||
│ ├── App.vue # 应用入口
|
||
│ ├── main.js # 应用入口 JS
|
||
│ ├── manifest.json # 应用配置
|
||
│ ├── pages.json # 页面配置
|
||
│ └── uni.scss # 全局样式
|
||
├── .env.development # 开发环境变量
|
||
├── .env.production # 生产环境变量
|
||
├── package.json # 项目依赖
|
||
├── tsconfig.json # TypeScript 配置
|
||
└── vite.config.js # Vite 配置
|
||
```
|
||
|
||
## 开发说明
|
||
|
||
### API 接口
|
||
|
||
小程序与 Web 端（life-script）共享同一套后端 API，接口文档参考 life-script 项目。
|
||
|
||
主要服务包括：
|
||
- **auth.js**: 用户认证（登录、注册、验证码）
|
||
- **userProfile.js**: 用户档案管理
|
||
- **lifeEvent.js**: 生命事件记录
|
||
- **epicScript.js**: AI 剧本生成
|
||
- **lifePath.js**: 实现路径规划
|
||
|
||
### 样式规范
|
||
|
||
小程序使用全局样式 + 组件作用域样式：
|
||
|
||
- **全局样式**: `src/App.vue` 中定义，包括玻璃态效果、渐变按钮、动画等
|
||
- **主题色**:
|
||
- 主背景：`#0F071A`
|
||
- 渐变顶部：`#1A0B2E`
|
||
- 渐变底部：`#050208`
|
||
- 主紫色：`#A855F7`
|
||
- 浅紫色：`#C084FC`
|
||
- 粉色：`#E879F9`
|
||
|
||
### 状态管理
|
||
|
||
使用 Pinia 进行状态管理，主要状态包括：
|
||
- `isLoggedIn`: 登录状态
|
||
- `userProfile`: 用户档案
|
||
- `events`: 生命事件列表
|
||
- `scripts`: 剧本列表
|
||
- `currentPath`: 当前实现路径
|
||
|
||
## 常见问题
|
||
|
||
### 端口占用
|
||
|
||
启动开发服务器前，如遇端口被占用：
|
||
|
||
```bash
|
||
# 清理占用端口的 vite 进程
|
||
./scripts/cleanup-all-vite.sh
|
||
# 或直接运行
|
||
vite
|
||
```
|
||
|
||
### 跨域问题
|
||
|
||
开发环境如遇跨域问题，请确保：
|
||
1. 后端 CORS 配置包含当前开发端口（5173-5190）
|
||
2. 使用正确的 API_BASE_URL
|
||
|
||
### 真机预览
|
||
|
||
1. 在微信开发者工具中点击「预览」
|
||
2. 使用微信扫描二维码
|
||
3. 在真机上查看效果
|
||
|
||
## 部署上线
|
||
|
||
### 小程序发布流程
|
||
|
||
1. **代码编译**: `npm run build:mp-weixin`
|
||
2. **导入工具**: 微信开发者工具导入编译后的目录
|
||
3. **上传代码**: 点击「上传」按钮
|
||
4. **版本管理**: 登录微信公众平台进行版本提交
|
||
5. **审核发布**: 提交审核后等待微信官方审核
|
||
|
||
### H5 部署
|
||
|
||
1. **代码编译**: `npm run build:h5`
|
||
2. **上传服务器**: 将 `unpackage/dist/build/h5` 目录部署到服务器
|
||
3. **配置反向代理**: 配置 Nginx 反向代理后端 API
|
||
|
||
## 参考资料
|
||
|
||
- [UniApp 官方文档](https://uniapp.dcloud.net.cn/)
|
||
- [Vue 3 官方文档](https://vuejs.org/)
|
||
- [微信小程序开发文档](https://developers.weixin.qq.com/miniprogram/dev/framework/)
|