uni-app 系列文章推荐:
一. 前言
终于,一直在维护的多个使用 HBuilder X
开发的 uni-app 项目,正在逐步迁移了!忍受了长时间的 Hbuilder X
开发工具,我最终决定放弃它,我现在终于可以使用 VSCode
开发 uni-app
项目了!
并不是说 Hbuilder X
不好,只是我适应不了,谁让我先遇到的是 VSCode
呢!
在之前的多个 uni-app
项目开发中,我使用的是 Hbuilder X
开发工具创建的,大部分是基于 Hbuilder X
+ Vue2
+ uView 1.0
来构建开发的,项目开发完成部署后,也一直没有机会升级。所以我的开发流程是:使用 VSCode
开发,然后使用 Hbuilder X
运行、打包、发布等等,是否有很多的人是这么使用的?
但是最近,在使用 HBuilder X
运行项目的过程中,出现了一个问题:长时间运行 HBuilder X
崩溃,导致电脑应用频繁崩溃,打开任何应用都会崩溃,只有电脑重启才会解决问题。起初我不知道是否为 HBuilder X
工具的问题,但是后来发现我只要不运行 HBuilder X 就没有问题。
因此,综上所述,我决定将之前的 uni-app
项目慢慢的全部转换为 Vue CLI
项目,以便更好地利用 VSCode
开发工具的优势。
在我将一个 uni-app
项目转换为 Vue CLI
项目的过程中,总结了一些经验和技巧,希望能对大家有所帮助。
同时在迁移的同时,也衍生出一个脚手架 create-colorful-app ,它可以帮助你快速初始化一个 uni-app 项目,包含使用以下 uni-app 相关技术栈:
目前 create-colorful-app
cli 仅支持 Vue2 项目的模板创建,后续会支持更多的项目,比如:uni-app、Vue2、Vue3、Angular、React 等等。
所以,如果你要迁移你的 uni-app 项目或重新开始一个新的 uni-app 项目,或许本文可以给你一下思路,我总结了以下几个重要的步骤:
- 初始化
uni-app
项目模板 - 迁移源代码:
src
目录 - 配置文件调整:
main.js
、vue.config.js
- 依赖项管理:
package.json
- 测试运行:h5、微信小程序、APP
接下来我们按照步骤开始吧!
二. 初始化项目模板
以基于 Vue2 版本的 uni-app 项目为例,可以通过以下两个方式快速初始化一个 Vue CLI 项目:
1. 使用脚手架 create-colorful-app
如果你要初始化一个全新的 uni-app Vue2 项目,建议使用 create-colorful-app
脚手架,内置快速开发的工具库 colorful-uni
,以帮助你简洁高效的开发应用:
create-colorful-app 是一个用于快速创建 uniapp 项目的轻量脚手架工具,它可以帮助你快速创建一个 uni-app 项目。
通过以下两种命令方式快速创建:
第一种,用 pnpm create
命令快速创建项目
pnpm create colorful-app
第二种,使用 npx
命令快速创建项目
npx create-colorful-app
注意:创建的项目默认使用了自研的开源工具库
colorful-uni
来快速实现一些功能,如果不想使用该工具库,也可以在项目中自行移除即可。
成功后会按需生成以下项目:
创建的项目有以下几个主要目录:
├── public # 静态资源文件
├── src # 主要源代码目录
├── ├── api # 网络请求目录
├── ├── components # 组件目录
├── ├── config # 环境配置目录
├── ├── pages # 页面
├── ├── static # 静态资源
├── └── store # Vuex模块
├── ├── App.vue # 应用的入口文件
├── ├── main.js # 主入口文件
├── ├── manifest.json # 应用配置文件
├── ├── pages.json # 应用路由配置文件
├── ├── uni.promisify.adaptor.js # 适配器
├── └── uni.scss # 全局的 SCSS 变量
├── package.json # 项目依赖
└── postcss.config.js # PostCSS 配置文件
2. 使用 Vue 脚手架 Vue CLI
注意:因为是Vue2项目,所以node版本不要太高,node版本应>=10.0.0 <18.0.0,我使用的v16.9.0,一切正常,大家参考!
当然,也可以通过 Vue CLI 的方式创建一个新的项目来作为基础模板。如果你还没有安装 Vue CLI,可以通过 npm 安装:
npm install -g @vue/cli
然后,使用 Vue CLI 创建一个新的项目:
vue create -p dcloudio/uni-preset-vue my-project
Vue 2 项目,建议使用以下命令直接进行创建:
# 建议使用 @vue/cli@4.5.14 创建,其他版本可能会有问题
npx @vue/cli@4.5.14 create -p dcloudio/uni-preset-vue uniapp-template
如果你使用 Vue CLI 方式创建项目,详细可以查看 uni-app 官方文档:通过 vue-cli 命令行创建 uni-app 应用
三. 迁移源代码
一般的,源代码迁移主要是将 HBuilderX 版本的 uni-app 项目中的源代码复制到新创建的 CLI 项目的相应目录中。
通常情况下,我们主要需要关注 src
目录,因为大部分的代码都会迁移到 src
目录。
主要会有以下文件目录和文件直接迁移到 src 目录下:
目录类:
- api 请求类目录
- assets 资源目录
- components 组件目录
- config 配置目录
- pages 页面目录
- static 静态资源目录
- store 状态管理目录
文件类:
- App.vue 应用入口文件
- main.js 主入口文件
- manifest.json 应用配置文件
- pages.json 应用路由配置文件
- uni.scss 全局的 SCSS 变量
如下图所示,变更前和变更后的目录文件对比:
将以上文件迁移到 src 目录下后,主要关注一些配置文件的调整和依赖项的管理是否需要调整,我们继续向下看。
四. 配置文件调整
配置文件调整主要涉及以下几个文件:
- manifest.json:应用配置文件
- uni.scss:全局的样式 scss 变量
- main.js:应用入口文件
- App.vue:主入口文件
- vue.config.js:Vue配置文件,如果你使用了它的话
检查并调整以上主要配置文件,确保应用的入口点正确配置,主要包括一些路径导入和声明。
五. 依赖项管理
检查 package.json
文件,确保所有必要的依赖项都已添加到新的 CLI 项目中,主要包括任何第三方库和一些必要插件。
一般为:
- Vue 的相关依赖
- @dcloudio、uni-app 的项目依赖
- scss 项目依赖:node-sass、sass-loader 等
- 第三方组件库
由于 HBuilderX
开发工具可能已经全局装了一下必要的依赖项,并没有体现在 package.json
中,所以之前我们的 package.json
文件的声明的依赖项比较少:
HBuilderX
开发工具全局装的插件项如下:
package.json
整体变更前后对比图如下:
变更完成之后,可以像执行 Vue 项目中的命令一样执行 uni-app 项目,其实就是一个引入 uni-app 依赖的 Vue 项目。
使用 npm 或 yarn 安装成功这些依赖项:
# npm
npm install
# 或者 yarn
yarn
六. 测试运行项目
在完成上述步骤后,尝试运行新的 Vue CLI 项目,看看是否有任何错误或警告。首先,我们不可能一次改动就成功,可以根据报错信息来更加精确的修改,这是验证转换是否成功的重要步骤。
使用以下命令运行或打包项目,platform 代表支持的平台:h5、mp-weixin、app-plus 等。
# 运行
# 默认启动 h5 浏览器预览
npm run dev:platform
# 或者
yarn dev:platform
# 打包
# 默认启动 h5 浏览器预览
npm run build:platform
# 或者
yarn build:platform
1. 测试 H5 运行
h5 是最常见的调试平台,方便且快捷,所以我们先测试一下 h5 运行。如果 h5 平台的运行和打包没有问题了,那么其他平台也不会有大问题。运行以下命令可以进行调试 h5:
# 运行
yarn dev
# 打包
yarn build
2. 测试小程序运行
# 运行
yarn dev:mp-weixin
# 打包
yarn build:mp-weixin
使用以上命令会在 dist/dev
或 dist/build
目录下生成对应的 mp-weixin
目录,使用微信开发者工具导入运行即可。
3. 测试 APP 运行
# 运行
yarn dev:app-plus
# 打包
yarn build:app-plus
通过以上的更改,运行命令调试、打包发布等流程,经过测试发现,均没有问题。
APP 打包运行最终还是离不开使用 HBuilderX 工具,所以如果你是选择云打包,还是需要使用 HBuilderX。但如果你是使用本地打包,完全就可以自主控制了。
关于 APP 打包,之前有一篇文章介绍,感兴趣的可以跳转阅读:【超详细】从 0 到 1 打包你的 uni-app 应用:安卓篇打包指南
小提示:
通过 CLI 的方式运行到 APP 平台,可以通过以下方式进行:
导入:打开 HBuilderX,选择 导入项目,选择 dist/dev/app-plus
文件夹即可。
运行:通过 yarn dev:app-plus
会在 dist/dev
目录下生成资源文件,然后打开 HBuilderX,导入刚刚生成的 dist/dev/app-plus
文件夹,选择 运行 -> 运行到手机或模拟器 -> 运行到 Android/iOS App 基座 即可。
打包:通过 yarn build:app-plus
会在 dist/build
目录下生成资源文件,然后打开 HBuilderX,导入刚刚生成的 dist/build/app-plus
文件夹,选择 发行 -> 原生 APP -> 云打包 即可。
七. 总结
本篇文章主要介绍了如何将 uni-app 正在开发的项目迁移到 VSCode,并使用 CLI 命令进行调试、打包和发布。主要步骤如下:
-
初始化 uni-app 项目模板:使用
Vue CLI
或create-colorful-app
脚手架初始化项目。 -
迁移代码:将 uni-app 项目的代码从 HBuilderX 迁移到 src 目录中。
-
配置环境变量:查看是否有配置文件的调整,以便能够正确运行 uni-app 项目。
-
安装依赖:安装 uni-app 项目所需的依赖,包括
@dcloudio
和Vue
的依赖和其他必要的依赖,主要是第三方插件和组件库。 -
运行调试:使用
yarn dev:platform
命令运行 uni-app 项目,并进行调试。 -
打包发布:使用
yarn build:platform
命令打包 uni-app 项目,并进行发布。
通过以上步骤正确的执行,我们就可以方便地在 VSCode 中进行 uni-app 项目的开发、调试和发布了。
终于舒服了,uni-app 老项目也可以使用 VSCode 愉快的开发了!