终于!我受够了 HBuilder X 开发 uni-app 项目 🔥

19,519 阅读9分钟

image.png

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 项目,或许本文可以给你一下思路,我总结了以下几个重要的步骤:

  1. 初始化 uni-app 项目模板
  2. 迁移源代码:src 目录
  3. 配置文件调整:main.jsvue.config.js
  4. 依赖项管理:package.json
  5. 测试运行: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 来快速实现一些功能,如果不想使用该工具库,也可以在项目中自行移除即可。

image.png

成功后会按需生成以下项目:

image.png

创建的项目有以下几个主要目录:

├── 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 变量

如下图所示,变更前和变更后的目录文件对比

image.png

将以上文件迁移到 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 开发工具全局装的插件项如下:

image.png

package.json 整体变更前后对比图如下:

image.png

变更完成之后,可以像执行 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

image.png

2. 测试小程序运行

# 运行
yarn dev:mp-weixin
# 打包
yarn build:mp-weixin

Snipaste_2024-11-27_13-56-27.png

使用以上命令会在 dist/devdist/build 目录下生成对应的 mp-weixin 目录,使用微信开发者工具导入运行即可。

3. 测试 APP 运行

# 运行
yarn dev:app-plus
# 打包
yarn build:app-plus

通过以上的更改,运行命令调试、打包发布等流程,经过测试发现,均没有问题。

image.png

APP 打包运行最终还是离不开使用 HBuilderX 工具,所以如果你是选择云打包,还是需要使用 HBuilderX。但如果你是使用本地打包,完全就可以自主控制了。

关于 APP 打包,之前有一篇文章介绍,感兴趣的可以跳转阅读:【超详细】从 0 到 1 打包你的 uni-app 应用:安卓篇打包指南

小提示

通过 CLI 的方式运行到 APP 平台,可以通过以下方式进行:

导入:打开 HBuilderX,选择 导入项目,选择 dist/dev/app-plus 文件夹即可。

Snipaste_2024-11-27_13-42-22.png

运行:通过 yarn dev:app-plus 会在 dist/dev 目录下生成资源文件,然后打开 HBuilderX,导入刚刚生成的 dist/dev/app-plus 文件夹,选择 运行 -> 运行到手机或模拟器 -> 运行到 Android/iOS App 基座 即可。

Snipaste_2024-11-27_13-43-20.png

打包:通过 yarn build:app-plus 会在 dist/build 目录下生成资源文件,然后打开 HBuilderX,导入刚刚生成的 dist/build/app-plus 文件夹,选择 发行 -> 原生 APP -> 云打包 即可。

Snipaste_2024-11-27_13-42-59.png

七. 总结

本篇文章主要介绍了如何将 uni-app 正在开发的项目迁移到 VSCode,并使用 CLI 命令进行调试、打包和发布。主要步骤如下:

  • 初始化 uni-app 项目模板:使用 Vue CLIcreate-colorful-app 脚手架初始化项目。

  • 迁移代码:将 uni-app 项目的代码从 HBuilderX 迁移到 src 目录中。

  • 配置环境变量:查看是否有配置文件的调整,以便能够正确运行 uni-app 项目。

  • 安装依赖:安装 uni-app 项目所需的依赖,包括 @dcloudioVue 的依赖和其他必要的依赖,主要是第三方插件和组件库。

  • 运行调试:使用 yarn dev:platform 命令运行 uni-app 项目,并进行调试。

  • 打包发布:使用 yarn build:platform 命令打包 uni-app 项目,并进行发布。

通过以上步骤正确的执行,我们就可以方便地在 VSCode 中进行 uni-app 项目的开发、调试和发布了。

终于舒服了,uni-app 老项目也可以使用 VSCode 愉快的开发了!

文档链接

vue-cli 创建 uni-app 应用

create-colorful-app 脚手架创建 uni-app 应用

uView UI 组件文档

colorful-uni 开发文档

colorful-uni 开源库,欢迎 Star、Fork