docs(mini-program): 更新 README 添加编译和部署说明
- 添加快速开始指南（安装依赖、开发模式） - 添加微信小程序编译和预览步骤 - 添加 H5 编译和部署说明 - 添加环境配置说明 - 添加项目结构说明 - 添加常见问题和部署上线流程 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
+223
-3
@@ -1,5 +1,225 @@
|
|||||||
# Vue 3 + TypeScript + Vite
|
# 人生 OS 微信小程序
|
||||||
|
|
||||||
This template should help get you started developing with Vue 3 and TypeScript in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.
|
基于 UniApp + Vue 3 的人生 OS 微信小程序，与 Web 端（life-script）共享后端 API。
|
||||||
|
|
||||||
Learn more about the recommended Project Setup and IDE Support in the [Vue Docs TypeScript Guide](https://vuejs.org/guide/typescript/overview.html#project-setup).
|
## 技术栈
|
||||||
|
|
||||||
|
- **框架**: 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
|
||||||
|
# 生产环境编译
|
||||||
|
npm run build:mp-weixin
|
||||||
|
# 或
|
||||||
|
pnpm build:mp-weixin
|
||||||
|
```
|
||||||
|
|
||||||
|
编译输出目录：`unpackage/dist/build/mp-weixin`
|
||||||
|
|
||||||
|
**部署步骤**：
|
||||||
|
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` 文件管理环境变量：
|
||||||
|
|
||||||
|
| 文件 | 说明 |
|
||||||
|
|------|------|
|
||||||
|
| `.env.development` | 开发环境配置 |
|
||||||
|
| `.env.production` | 生产环境配置 |
|
||||||
|
|
||||||
|
**开发环境配置**（`.env.development`）：
|
||||||
|
```bash
|
||||||
|
VITE_APP_ENV=dev
|
||||||
|
VITE_API_BASE_URL=http://localhost:19089
|
||||||
|
VITE_WS_URL=ws://localhost:19089
|
||||||
|
VITE_DEBUG=true
|
||||||
|
```
|
||||||
|
|
||||||
|
**生产环境配置**（`.env.production`）：
|
||||||
|
```bash
|
||||||
|
VITE_APP_ENV=prod
|
||||||
|
VITE_API_BASE_URL=http://101.200.208.45:19089/api
|
||||||
|
VITE_WS_URL=ws://101.200.208.45:19089
|
||||||
|
VITE_DEBUG=false
|
||||||
|
```
|
||||||
|
|
||||||
|
## 项目结构
|
||||||
|
|
||||||
|
```
|
||||||
|
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/)
|
||||||
|
|||||||
Reference in New Issue
Block a user