# 开发指南
## 环境搭建
### 必需软件
1. **HBuilderX** 或 **Visual Studio Code**
2. **微信开发者工具** (开发微信小程序时)
3. **Android Studio** (开发 App 时)
4. **Xcode** (开发 iOS App 时,仅 macOS)
### Node.js 环境
```bash
# 检查 Node.js 版本
node -v # 需要 >= 12
# 检查 npm 版本
npm -v
# 安装依赖
npm install
# 或使用 yarn
yarn install
```
## 项目配置
### 环境配置
修改 `common/config.js` 配置不同环境:
```javascript
// 生产环境
export const apiBaseUrl = 'https://backend.qicai321.com';
// 测试环境
export const apiBaseUrl = 'http://192.168.66.187:8083';
```
### 微信小程序配置
在 `manifest.json` 中配置小程序 AppID:
```json
{
"mp-weixin": {
"appid": "wxc9655eeaa3223b75",
"setting": {
"urlCheck": false
}
}
}
```
## 开发流程
### 1. 启动开发服务器
```bash
# H5 开发
npm run dev:h5
# 微信小程序开发
npm run dev:mp-weixin
# App 开发 (需要在 HBuilderX 中运行)
```
### 2. 页面开发
创建新页面的步骤:
1. **创建页面文件**
在 `pages` 目录下创建新的目录和 .vue 文件:
```
pages/
new-page/
new-page.vue
```
2. **配置页面路由**
在 `pages.json` 中添加页面配置:
```json
{
"path": "pages/new-page/new-page",
"style": {
"navigationBarTitleText": "新页面"
}
}
```
3. **页面跳转**
```javascript
// 保留当前页面,跳转到应用内的某个页面
uni.navigateTo({
url: '/pages/new-page/new-page'
});
// 关闭当前页面,跳转到应用内的某个页面
uni.redirectTo({
url: '/pages/new-page/new-page'
});
// 跳转到 tabBar 页面
uni.switchTab({
url: '/pages/index/index'
});
```
### 3. API 调用
#### 使用封装的 API
```javascript
// 方式一:直接导入
import { getUserInfo } from '@/api/user.js';
export default {
methods: {
async fetchData() {
try {
const userInfo = await getUserInfo();
console.log(userInfo);
} catch (error) {
console.error('获取用户信息失败:', error);
}
}
}
}
```
#### 使用 Composition API
```javascript
import { useUserApi } from '@/composables/useUserApi.js';
export default {
setup() {
const { fetchUserInfo, loading, error } = useUserApi();
const loadData = async () => {
try {
const data = await fetchUserInfo();
console.log(data);
} catch (err) {
console.error(error.value);
}
};
return {
loadData,
loading,
error
};
}
}
```
### 4. 样式开发
#### 使用 rpx 单位
uni-app 使用 rpx 作为响应式单位:
```css
/* 750rpx 等于屏幕宽度,自适应不同屏幕 */
.container {
width: 750rpx;
height: 200rpx;
padding: 20rpx;
}
```
#### 常用样式类
```css
/* 弹性布局 */
.flex {
display: flex;
}
.flex-column {
flex-direction: column;
}
/* 居中对齐 */
.center {
display: flex;
align-items: center;
justify-content: center;
}
/* 按钮样式 */
.btn-primary {
background-color: #0039b3;
color: #fff;
border-radius: 44rpx;
height: 88rpx;
line-height: 88rpx;
text-align: center;
}
```
## 调试技巧
### 1. 控制台调试
```javascript
// 在页面中使用
console.log('调试信息', data);
console.error('错误信息', error);
console.warn('警告信息', warning);
```
### 2. 条件编译
针对不同平台开发:
```javascript
// #ifdef APP-PLUS
console.log('App 平台');
// #endif
// #ifdef MP-WEIXIN
console.log('微信小程序');
// #endif
// #ifdef H5
console.log('H5 平台');
// #endif
```
### 3. 真机调试
App 真机调试:
1. 连接手机到电脑
2. 在 HBuilderX 中选择 "运行" → "运行到手机或模拟器"
3. 选择设备并运行
微信小程序调试:
1. 在微信开发者工具中打开项目
2. 点击 "预览" 或 "真机调试"
3. 使用微信扫码在手机上查看
### 4. 网络请求调试
查看网络请求:
```javascript
// 在 utils/request.js 中已有 console.log
console.log('request:', options);
console.log('response:', response);
```
使用抓包工具:
- Charles/Fiddler: 抓取 HTTP/HTTPS 请求
- 微信开发者工具: 查看小程序网络请求
## 构建部署
### 构建 H5
```bash
npm run build:h5
```
构建产物在 `unpackage/dist/build/h5`
### 构建微信小程序
```bash
npm run build:mp-weixin
```
构建产物在 `unpackage/dist/build/mp-weixin`
### 构建 App
1. 在 HBuilderX 中选择 "发行" → "原生 App-云打包"
2. 配置打包参数
3. 提交打包
## 常见问题
### 1. 页面跳转失败
**问题**: 跳转后白屏或报错
**解决方案**:
- 检查页面路径是否正确
- 检查 `pages.json` 配置是否正确
- 检查页面文件是否存在语法错误
### 2. API 请求失败
**问题**: 网络请求返回 404 或 500
**解决方案**:
- 检查 API 地址是否正确
- 检查网络连接
- 检查后端服务是否正常
- 查看控制台错误信息
### 3. 样式不生效
**问题**: CSS 样式显示不正确
**解决方案**:
- 检查选择器是否正确
- 使用 `!important` 提高优先级
- 检查 scoped 是否影响样式
- 使用 rpx 而非 px
### 4. 真机调试问题
**问题**: 真机上无法正常运行
**解决方案**:
- 检查手机是否允许 USB 调试
- 检查防火墙设置
- 尝试重启调试工具
- 查看真机运行日志
### 5. Token 过期
**问题**: 请求返回 401 未授权
**解决方案**:
- 清除本地 token: `uni.removeStorageSync('token')`
- 重新登录获取新 token
- 添加全局请求拦截器处理 token 刷新
## 代码规范
### 命名规范
1. **变量命名**: 使用驼峰命名法
```javascript
const userName = 'John';
const isLogin = true;
```
2. **方法命名**: 使用动词开头
```javascript
function getUserInfo() {}
function handleLogin() {}
function fetchData() {}
```
3. **组件命名**: 使用 PascalCase
```vue
```
### 文件结构
```
pages/
page-name/
page-name.vue # 页面文件
page-name.js # 页面逻辑(如果复杂)
page-name.scss # 页面样式(如果复杂)
```
### 注释规范
```javascript
/**
* 获取用户信息
* @param {Number} userId - 用户ID
* @returns {Promise} - 用户信息
*/
export function getUserInfo(userId) {
// 实现代码
}
```
## 版本管理
### Git 工作流
```bash
# 创建新分支
git checkout -b feature/new-feature
# 提交代码
git add .
git commit -m "feat: 添加新功能"
# 推送分支
git push origin feature/new-feature
```
### 提交信息规范
- `feat`: 新功能
- `fix`: 修复 bug
- `docs`: 文档更新
- `style`: 代码格式调整
- `refactor`: 代码重构
- `test`: 添加测试
- `chore`: 构建过程或辅助工具的变动
## 性能优化
### 1. 图片优化
- 使用压缩后的图片
- 使用 WebP 格式(H5 平台)
- 懒加载图片
### 2. 代码分割
```javascript
// 按需加载组件
const Component = () => import('@/components/Component.vue');
```
### 3. 数据缓存
```javascript
// 缓存 API 数据
const cachedData = uni.getStorageSync('cachedData');
if (cachedData) {
// 使用缓存数据
} else {
// 请求新数据
}
```
### 4. 防抖和节流
```javascript
// 防抖
function debounce(func, wait) {
let timeout;
return function() {
clearTimeout(timeout);
timeout = setTimeout(func, wait);
};
}
// 节流
function throttle(func, limit) {
let inThrottle;
return function() {
if (!inThrottle) {
func.apply(this, arguments);
inThrottle = true;
setTimeout(() => inThrottle = false, limit);
}
};
}
```
## 测试
### 单元测试
```javascript
// 测试 API 方法
import { getUserInfo } from '@/api/user.js';
test('getUserInfo should return user data', async () => {
const userInfo = await getUserInfo();
expect(userInfo).toHaveProperty('id');
});
```
### 集成测试
- 测试完整的用户流程
- 测试页面跳转
- 测试表单提交
### 真机测试
- 在不同设备上测试
- 测试不同网络环境
- 测试边界情况