1. 开发环境搭建:从零开始配置uni-app微信小程序项目
作为一名长期使用VSCode的前端开发者,我完全理解为什么很多同行不愿意切换到HBuilder。虽然uni-app官方推荐使用HBuilder,但VSCode的灵活性和丰富的插件生态确实难以替代。下面是我在VSCode中搭建uni-app开发环境的完整过程。
1.1 项目初始化与模板选择
创建uni-app项目的第一步是选择合适的模板。uni-app官方提供了多种预设模板,对于新项目,我强烈推荐使用Vue3 + TypeScript的组合:
bash复制npx degit dcloudio/uni-preset-vue#vite-ts hello-uniapp
这里有几个技术选型的考量:
- Vue3相比Vue2有更好的性能和维护性
- TypeScript能大幅提升代码质量,特别是在团队协作中
- Vite作为构建工具,比传统webpack快很多
注意:由于网络问题,直接从GitHub克隆可能会失败。这是国内开发者常见的问题,官方很贴心地提供了Gitee镜像。如果遇到网络问题,可以直接下载Gitee上的模板压缩包:
vite-ts模板Gitee下载链接
1.2 开发工具配置
解压模板后,用VSCode打开项目,需要安装以下必备插件:
- uni-app插件 - 提供语法高亮和代码提示
- Volar - Vue3官方推荐的VSCode插件
- TypeScript Vue Plugin - 增强TS在Vue文件中的支持
安装完插件后,项目结构大致如下:
code复制hello-uniapp/
├── src/
│ ├── pages/ # 页面目录
│ ├── static/ # 静态资源
│ └── App.vue # 应用入口
├── package.json # 项目配置
└── vite.config.ts # Vite配置
1.3 依赖安装与版本管理
打开package.json,你会看到uni-app项目的主要依赖:
json复制{
"dependencies": {
"@dcloudio/uni-app": "^3.0.0",
"vue": "^3.2.0"
},
"devDependencies": {
"@dcloudio/types": "^3.0.0",
"@vitejs/plugin-vue": "^3.0.0",
"typescript": "^4.0.0",
"vite": "^3.0.0"
}
}
运行npm install安装依赖时,有几点需要注意:
- Node.js版本建议使用16.x或18.x LTS版本
- 如果安装失败,可以尝试删除node_modules和package-lock.json后重试
- 国内用户可以使用cnpm或设置淘宝镜像加速安装
2. 微信小程序开发配置
2.1 微信开发者工具准备
在开始uni-app开发前,需要准备好微信小程序开发环境:
- 注册微信小程序账号(个人或企业)
- 获取AppID - 这是小程序的唯一标识
- 下载微信开发者工具 - 建议下载稳定版
提示:即使使用uni-app开发,最终还是要依赖微信开发者工具进行调试和发布,所以这个步骤不能跳过。
2.2 uni-app与微信小程序的关联
uni-app通过编译将Vue组件转换为微信小程序的WXML/WXSS/JS。这个过程是自动的,但需要正确配置:
- 在manifest.json中配置微信小程序AppID:
json复制{
"mp-weixin": {
"appid": "你的微信小程序AppID",
"setting": {
"urlCheck": false
}
}
}
- 运行开发命令:
bash复制npm run dev:mp-weixin
这个命令会:
- 启动Vite开发服务器
- 监听文件变化
- 实时编译到dist/dev/mp-weixin目录
2.3 项目导入与调试
在微信开发者工具中:
- 点击"导入项目"
- 选择uni-app项目下的dist/dev/mp-weixin目录
- 确保AppID正确(可以使用测试号)
导入成功后,你会看到:
- 左侧是模拟器
- 右侧是调试工具
- 底部是编译日志
3. 开发工作流与实时预览
3.1 高效的开发循环
uni-app + VSCode + 微信开发者工具的组合提供了很棒的工作流:
- 在VSCode中编辑Vue组件
- 保存后自动触发重新编译
- 微信开发者工具自动刷新预览
这个过程中有几个优化点:
- 在VSCode中配置保存时自动格式化(推荐使用Prettier)
- 微信开发者工具中可以开启"自动保存时重新编译"
- 合理使用VSCode的代码片段功能提高开发效率
3.2 真机调试技巧
点击微信开发者工具上的"预览"按钮,会生成二维码,用微信扫描即可在手机上预览。但这里有几个常见问题:
-
手机预览与模拟器显示不一致
- 检查小程序基础库版本是否一致
- 确保手机微信版本是最新的
- 尝试清除手机小程序缓存
-
出现
Can't find variable: __wxAppCode__错误- 这是微信小程序运行时环境的问题
- 解决方案:在微信开发者工具中点击"详情"->"本地设置"->勾选"调试基础库自动更新"
-
样式异常
- uni-app的rpx单位在不同设备上可能有差异
- 可以在App.vue中设置基准宽度:
css复制page { font-size: 16px; }
4. 常见问题与解决方案
4.1 网络请求问题
微信小程序对网络请求有特殊限制:
- 必须使用HTTPS
- 域名需要在后台配置
- 开发阶段可以勾选"不校验合法域名"
在uni-app中,推荐使用uni.request:
javascript复制uni.request({
url: 'https://api.example.com/data',
success: (res) => {
console.log(res.data);
}
});
4.2 跨端兼容性问题
uni-app虽然支持多端,但各平台仍有差异。处理方式:
- 使用条件编译:
javascript复制// #ifdef MP-WEIXIN
console.log('微信小程序特有代码');
// #endif
- 平台特定样式:
css复制/* 微信小程序特有样式 */
/* #ifdef MP-WEIXIN */
.button {
padding: 10rpx;
}
/* #endif */
4.3 性能优化建议
-
图片优化:
- 使用CDN加速
- 合理压缩图片
- 使用webp格式
-
减少setData调用:
- 合并数据更新
- 避免频繁更新大数组
-
使用分包加载:
json复制{
"subPackages": [
{
"root": "pages/sub",
"pages": [
"index",
"detail"
]
}
]
}
5. 项目结构与最佳实践
5.1 合理的目录结构
经过多个uni-app项目实践,我总结出这样的目录结构:
code复制src/
├── components/ # 公共组件
├── composables/ # Vue组合式函数
├── pages/ # 页面
├── static/ # 静态资源
├── store/ # 状态管理
├── utils/ # 工具函数
├── App.vue # 应用入口
└── main.ts # 应用配置
5.2 状态管理方案
对于复杂应用,推荐使用Pinia:
- 安装:
bash复制npm install pinia @pinia/nuxt
- 创建store:
typescript复制// store/user.ts
import { defineStore } from 'pinia';
export const useUserStore = defineStore('user', {
state: () => ({
name: '',
token: ''
}),
actions: {
login() {
// 登录逻辑
}
}
});
- 在组件中使用:
javascript复制import { useUserStore } from '@/store/user';
const user = useUserStore();
user.login();
5.3 代码规范与团队协作
- 使用ESLint + Prettier统一代码风格
- 配置Git钩子自动检查
- 编写清晰的组件文档
- 使用TypeScript接口定义数据类型
6. 调试与发布
6.1 高级调试技巧
- 使用微信开发者工具的"Sources"面板调试TypeScript源码
- 在uni-app配置中开启sourcemap:
javascript复制// vite.config.ts
export default defineConfig({
build: {
sourcemap: true
}
});
- 使用console增强调试:
javascript复制console.table(data); // 以表格形式输出
console.dir(component); // 查看组件实例
6.2 发布流程
- 构建生产版本:
bash复制npm run build:mp-weixin
-
在微信开发者工具中:
- 点击"上传"
- 填写版本号和备注
- 提交审核
-
在小程序管理后台:
- 审核通过后发布
- 配置服务器域名
- 设置业务域名
6.3 持续集成方案
可以配置自动化发布流程:
- GitHub Actions自动构建
- 自动上传到微信平台
- 钉钉/企业微信通知
示例配置:
yaml复制name: Build and Deploy
on:
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- run: npm install
- run: npm run build:mp-weixin
- uses: wechat-miniprogram/miniprogram-ci-action@v1
with:
appid: ${{ secrets.APPID }}
privateKey: ${{ secrets.PRIVATE_KEY }}
projectPath: dist/build/mp-weixin
version: ${{ github.run_number }}
desc: ${{ github.event.head_commit.message }}
经过多个uni-app项目的实践,我发现这套工作流非常高效。VSCode提供了优秀的开发体验,而uni-app的跨端能力又大大提高了代码复用率。对于刚接触uni-app的开发者,建议从小项目开始,逐步熟悉整个生态。