uni-app 用久了你会发现真正高效的项目创建方式往往不是打开可视化工具点按钮而是命令行。作为一个多端开发框架uni-app 的项目初始化方式直接决定了后续的工程化程度。命令行创建 uni-app 项目不仅方便版本管理、自动化部署还能把项目模板固化到团队的工作流里新成员拉下来就能跑。这篇内容我会从环境准备、创建流程、项目结构、编译运行到常见坑点完整梳理一遍基于命令行的 uni-app 项目创建与使用过程适合刚开始接触 CLI 方式、或者打算从 HBuilderX 迁移到命令行开发的开发者参考。1. 为什么选择命令行方式创建 uni-app 项目1.1 可视化创建与命令行创建的差别很多人第一次接触 uni-app 是从 HBuilderX 的界面操作开始的新建项目、选择模板、点击创建整个过程不到一分钟非常符合“开箱即用”的感觉。但这种方式有一个比较现实的问题项目一旦从编辑器里诞生它就和编辑器强绑定了。如果你换一台电脑、换一个编辑器或者团队里有人用其他 IDE那这个项目的打开方式就会变得别扭。命令行创建则完全不同。它本质上是一个标准的 Node.js 项目项目里所有的依赖、配置、源码都通过文件管理创建过程只依赖 npm 或 yarn 这类包管理工具。你不需要在某个图形界面里操作只需要在终端里执行几条命令项目就被初始化出来了。用生活化的类比来说可视化创建有点像在餐厅点一份套餐方便省事但食材搭配是后厨定好的你想换配菜只能通过界面上的有限选项命令行创建则像是自己去菜市场按清单采购虽然多了一步但每一步都可以掌控甚至可以把自己的购物清单项目模板分享给别人用。1.2 命令行方式在团队协作中的实际价值团队协作场景下命令行方式的价值会被放大得特别明显。首先基于命令行的项目天然适配 Git 工作流。项目创建完成后所有配置都是文件团队成员 clone 下来之后只需要执行一次 npm install 就能把环境恢复不需要每个人都去手动创建一遍项目。其次是升级路径更清晰。uni-app 的 CLI 项目依赖是通过 package.json 管理的升级框架时只需要改依赖版本号再重新安装即可。比如你想从 Vue 2 版本升级到 Vue 3 版本或者在 vue3 与 vue2 模板之间切换命令行项目的处理方式比可视化项目要明确得多至少你不用在新旧项目之间手动迁移代码。第三点是和持续集成流程的配合。命令行创建的项目天然可以接入自动化流水线提交代码后自动安装依赖、执行编译、产出小程序包或 H5 包这些都是可视化创建方式很难做到的。我在实际项目里就是这样处理的本地用命令行创建项目push 到仓库后流水线自动触发构建测试人员直接拿构建产物测试整个流程非常顺。1.3 什么场景下应该优先选择命令行创建如果你是个人学习者或者只是临时写个小 demo可视化创建反而更直接没必要为了用命令行而用命令行。但如果你的项目有以下任一特征我会建议优先考虑命令行方式项目需要长期维护并且会持续迭代版本团队多人协作需要统一的脚手架和依赖管理项目要接入自动化测试、持续集成或自动部署流程你希望在 Vue 生态的常规开发习惯下工作比如使用 VSCode、WebStorm 等编辑器项目要同时维护多个端小程序、H5、App并且希望编译逻辑是可配置、可重复的简单说命令行创建适合“严肃”一点的项目可视化创建适合“快速验证”的项目。二者并不冲突但如果你正在往工程化的方向走命令行是绕不开的一条路。2. 环境准备搭建可用的命令行开发环境2.1 Node.js 版本与包管理器选择命令行创建 uni-app 项目的前提是本地环境具备 Node.js。这里有一个非常容易踩的坑Node.js 版本过低或者过高都可能导致依赖安装失败或者编译报错。以我常用的官方 CLI 模板为例它依赖了 Vue CLI 相关工具链这些工具链对 Node.js 的版本有明确要求。Vue CLI 4.x 要求 Node.js 版本不低于 8.9但实际推荐使用长期支持版本。如果你用的是 Node.js 12 以下的版本安装依赖的时候大概率会遇到语法或者兼容性错误。反过来如果你装了特别新的 Node.js 20某些老模板里的依赖可能还没有完全适配会出现 node-sass 编译失败之类的问题。我的建议是Node.js 版本选择 14.x 或 16.x 的 LTS 版本这两个版本在 uni-app CLI 项目里被验证得最充分。如果你同时管理多个项目推荐用 nvm 或 fnm 这类 Node 版本管理工具按项目切换版本而不是把所有项目都放在同一个 Node 环境下。包管理器方面npm 是默认选择它随 Node.js 一起安装不需要额外配置。如果下载依赖速度比较慢可以配置国内镜像源比如npm config set registry https://registry.npmmirror.com如果你更喜欢 yarn完全没问题uni-app 官方模板同时支持 npm 和 yarn但注意不要在同一个项目里混用 lock 文件避免出现依赖版本不一致的问题。2.2 准备官方 CLI 模板的几种方式命令行创建 uni-app 项目核心是使用官方提供的预设模板。目前常见的有两种方式一种是通过 vue-cli 的 preset 方式创建另一种是直接使用官方提供的模板仓库。vue-cli 方式是我最早接触也最常用的一种。先安装 vue-cli 工具然后执行npm install -g vue/cli安装完成后通过 vue create 命令配合官方预设来创建 uni-app 项目vue create -p dcloudio/uni-preset-vue my-project这条命令的意思是使用 dcloudio/uni-preset-vue 这个预设模板在当前目录下创建一个名为 my-project 的项目。执行过程会询问你想要 Vue 2 还是 Vue 3 版本根据需求选择即可。另一种方式是直接使用 degit 拉取模板仓库比如npx degit dcloudio/uni-preset-vue#vue3 my-projectdegit 的特点是快它不会拉取完整 git 历史只会下载当前版本的文件适合快速初始化。我个人的体会是vue-cli 方式比较中规中矩degit 方式更轻量看你的习惯。提供两条路是希望你在不同场景下能选顺手的那条。2.3 验证环境是否就绪环境准备的最后一步是确认所有工具都可用。我一般会依次执行这几个命令node -v npm -v vue --version如果 vue 命令提示找不到说明全局安装没有成功或者 npm 的全局 bin 目录没有加到系统环境变量里。这个问题在 Windows 上比较常见但很好解决重新安装 vue-cli 或者在终端里配置一下 PATH 环境变量即可。还有一个容易被忽略的点如果你的电脑上已经装了 HBuilderX它自带了一个 Node 环境这个环境是给 HBuilderX 内部插件用的和系统全局 Node 是两套东西。命令行方式创建项目用的必须是系统全局的 Node你在终端里执行 node -v 能正确输出版本号说明当前终端用的是全局环境。如果发现终端里找不到 node但 HBuilderX 内部又能用相关功能不用惊讶它们本来就是分离的。3. 命令行创建 uni-app 项目的完整流程3.1 使用官方预设模板创建项目的实际操作环境准备好之后创建项目本身就是一条命令的事。以 vue-cli 方式为例完整过程如下vue create -p dcloudio/uni-preset-vue my-uni-demo命令执行后终端会进入交互模式询问你要创建哪种模板Preset options: ❯ 默认模板Vue 3 默认模板Vue 2这里说一下如何选择如果你的项目要从零开始且没有老代码兼容负担直接选 Vue 3 模板。Vue 3 的组合式 API 写起来更简洁而且 uni-app 对 Vue 3 的支持已经非常成熟。如果项目业务代码比较老或者依赖了只适配 Vue 2 的第三方库那就选 Vue 2 模板。在这个选择上不要纠结太久两个版本的项目结构基本一致后续想升级也还有路径可走。选定模板后工具会自动拉取依赖并完成初始化这个过程耗时取决于网络情况。如果网络状态一般可能会在安装依赖这一步卡几分钟不要误以为卡死了耐心等一等。依赖安装完成后终端会输出成功提示并告诉你接下来可以执行什么命令启动开发服务。3.2 创建后的目录结构逐层拆解项目创建完成后第一件事是看一下目录结构。虽然每个项目的业务代码都不一样但 CLI 创建出来的 uni-app 项目骨架是一样的。拿 Vue 3 模板举例核心目录和文件如下my-uni-demo/ ├── src/ │ ├── pages/ │ │ └── index/ │ │ └── index.vue │ ├── static/ │ ├── App.vue │ ├── main.js │ ├── manifest.json │ ├── pages.json │ └── uni.scss ├── index.html ├── package.json ├── vite.config.js └── .gitignoresrc 目录是源码主目录pages 里放页面App.vue 是应用入口组件main.js 是 JS 入口manifest.json 管理应用配置pages.json 配置页面路由与窗口样式uni.scss 存放全局样式变量。material.json 和 pages.json 这两个文件是 uni-app 项目里最核心的配置文件开发多端应用时很多跨端兼容的策略都要在它们里面做文章。页面新增、tabBar 配置、导航栏样式、权限申请等等都是在 pages.json 里操作的。index.html 是 H5 端的入口模板只有当你把项目运行到浏览器时才会用到。vite.config.js 是 Vite 的配置文件CLI 创建的项目默认使用 Vite 作为构建工具相比老版本的 webpack 方案冷启动和热更新速度都会更快。还有一点值得说明CLI 创建的项目默认不包含 HBuilderX 特有的项目文件如果你之前用 HBuilderX 打开 CLI 项目可能会遇到提示。但这不影响正常开发HBuilderX 可以导入 CLI 项目只是它的项目管理方式和纯 CLI 项目稍有不同实际用起来问题不大。3.3 安装依赖后的可用命令说明CLI 项目安装完依赖后package.json 里的 scripts 脚本决定了你日常要怎么运行项目。vue3 模板里常见的 scripts 命令大概有这些npm run dev:mp-weixin npm run dev:h5 npm run build:mp-weixin npm run build:h5dev 系列命令是开发模式启动开发服务器并监听文件变化进行实时编译build 系列是生产构建会做代码压缩、文件名指纹等处理。把命令拆开看都是 dev: 或 build: 加上目标平台名称比如 mp-weixin 指微信小程序app 指 App 平台h5 指 H5 平台。我一般拿到一个新项目先执行 npm run dev:mp-weixin确认能编译通过再在微信开发者工具里看效果。这一步没问题说明项目本身是健康的后续改代码只会遇到业务逻辑问题而不是环境问题。4. 项目配置与运行到小程序平台4.1 manifest.json 与 pages.json 的核心配置项命令行创建出来的项目manifest.json 和 pages.json 都是初始状态需要根据实际项目需求做调整。manifest.json 里最重要的几个配置项包括应用名称、appid、平台 SDK 配置、权限声明等。以微信小程序为例在运行到微信小程序之前需要把微信小程序的 appid 填进去。如果还没有注册小程序账号可以先使用测试号也可以不填 appid微信开发者工具会以游客模式打开项目但部分 API 会被限制。我踩过的坑是明明微信开发者工具里可以正常预览但手机扫码后页面是空白的排查了很久发现是 manifest.json 里没有配置微信小程序的 appid导致部分接口请求被拦截。所以如果做正式项目appid 一定要第一时间配上。pages.json 里则要配置页面路由和窗口表现。CLI 模板默认只有一个 index 页面你的业务肯定不止一个页面所以新增页面时需要同步在这里注册路由。举个例子新增一个 pages/user/user 页面pages.json 的 pages 数组里就要加一条记录{ path: pages/user/user, style: { navigationBarTitleText: 个人中心 } }配置完成后保存开发模式会自动刷新新页面就能通过 uni.navigateTo 等 API 跳转了。pages.json 还支持配置 tabBar、globalStyle、condition 等字段这里不展开但你要知道项目运行得顺不顺利相当一部分取决于这个文件的配置有没有写对。4.2 运行到微信小程序的完整命令流程当项目配置完成后把项目运行到微信小程序的流程基本是固定的。先在终端里执行npm run dev:mp-weixin这条命令会启动编译监听模式实时把 src 目录下的代码编译成微信小程序能识别的文件默认输出到 dist/dev/mp-weixin 目录。编译成功后终端会显示类似“Build complete”的提示。然后打开微信开发者工具选择“导入项目”把目录指向 dist/dev/mp-weixin。项目名称和 appid 按实际情况填写就可以看到内容了。在开发者工具里你需要确认几个设置本地设置里开启 ES6 转 ES5如果需要使用某些新特性还要勾选对应的增强编译选项。开发模式下代码改动会实时触发编译微信开发者工具会自动刷新。如果发现改动后终端里有编译报错但工具里还是旧内容通常是因为编译进程挂了回终端看一眼报错信息修复后重新触发编译即可。4.3 常见运行报错与微信开发者工具的配合细节命令行项目第一次导入微信开发者工具比较容易遇到的问题是工具提示“未找到 app.json”。这个报错的原因几乎都是目录导入错了。你要导入的目录是 dist/dev/mp-weixin而不是项目根目录。小程序编译产物会生成自己的 app.json 文件这个文件位于 dist 目录下因此导入的必须是编译输出目录。另一个常见问题是编译成功但页面空白。从 CLI 创建的 Vue 2 模板迁移到 Vue 3 模板时如果代码里混用了 Vue 2 的选项式写法和 Vue 3 的组合式 API运行到小程序可能出现运行时错误。解决思路是确认项目模板版本与代码写法一致或者从模板提供的示例页面开始改不要一上来就搬老项目代码。还有一点和微信开发者工具有关工具默认的调试基础库版本可能和 uni-app 编译出的代码不兼容小程序页面无法正常渲染时可以考虑在工具里切换调试基础库版本通常选择最新版本或次新版本能解决问题。提示运行到微信小程序时项目里的 uni.scss 如果写了特殊语法编译早期容易报错建议优先使用官方默认样式变量再逐步替换成自定义变量。5. 命令行创建与编译的常见问题排查5.1 创建阶段容易踩的坑和解决办法创建阶段的问题集中在两类一类是模板拉取失败另一类是依赖安装超时或报错。模板拉取失败多半是网络原因。vue-cli 拉取预设模板需要访问远程仓库如果网络不稳定会失败。解决办法有两个重试几次或者改用国内镜像源。vue-cli 本身支持配置镜像在用户目录下的 .vuerc 文件里可以编辑 useTaobaoRegistry 字段把它设为 true后续拉取依赖会走镜像速度会提升不少。依赖安装阶段的报错最常见的是 node-sass 或 node-sass 相关的安装失败。这个问题在 Node.js 版本过高时特别明显因为 node-sass 需要下载对应的二进制文件网络不好或者版本不匹配就容易失败。如果遇到这个错误我的建议是优先检查 Node 版本尽量使用 16.x 或 14.x然后再重新安装。还要注意一个细节如果项目名用了中文或者包含空格的路径某些依赖工具在编译时可能会出问题。我见过不少开发者因为项目路径里有中文目录导致编译报错找不到模块最后花了大量时间排查。建议项目路径和项目名都用英文不要有空格。5.2 推荐使用的依赖安装与构建提速方案CLI 项目的依赖安装速度对开发体验影响很大。如果你每次 npm install 都要等十几分钟时间久了会很崩溃。我的做法是项目初始化阶段就配置好镜像源并且使用 npm ci 代替 npm install 进行依赖恢复。npm ci 和 npm install 的区别在于npm ci 会严格按照 package-lock.json 安装依赖安装速度快且不会因为 lock 文件不一致而引入版本偏差。在持续集成流程里npm ci 是更推荐的方式。编译提速方面Vue 3 模板默认使用 Vite冷启动已经比老项目快很多。如果你用的是 Vue 2 模板且项目规模变大编译时间明显增加可以考虑更换开发工具链或者在构建配置里开启缓存。不过坦白讲在没有特殊需求的情况下优先选择 Vue 3 模板是最省心的路径。5.3 多端开发时维护命令行项目的经验心得命令行项目一旦接入了多端输出你会发现一个事实同一套代码编译到不同平台表现不一定完全一致。比如某些 CSS 样式在 H5 上正常在微信小程序里可能需要特殊处理。这不是命令行方式的局限而是 uni-app 这个框架本身的跨端特性决定的。我的经验是在任何一段业务代码提交前至少要运行一次微信小程序和 H5 两个平台的编译确保没有平台专属的编译错误。命令行的好处是这种多端编译可以并行跑开两个终端分别执行 dev:mp-weixin 和 dev:h5哪个报错立刻就能看到。多人协作场景下比较容易被忽视的是 .gitignore 的维护。CLI 项目模板默认会忽略 node_modules 和 dist 目录这一点不需要动但如果你在本地配置了什么私有的临时目录一定要及时补到 .gitignore 里避免污染仓库。另外项目里的 package-lock.json 或 yarn.lock 必须提交到仓库这是保证团队依赖一致性的关键。注意尽量不要在 src 目录之外放业务代码尤其不要依赖 src 目录之外的文件。uni-app 编译时是以 src 为根目录的放在外面会导致编译产物缺失而且排查起来很费时间。从我自己的实际操作体会来说命令行创建 uni-app 项目最大的好处是把项目的生命周期从“创建一次就管终身”变成了“可复制、可重建、可自动化”的过程。刚开始从 HBuilderX 切换到命令行时可能会觉得多了一圈操作但用上一个项目后你就会发现所有和环境相关的东西都变得可控了换电脑、加新成员、搭流水线都没有原来那么费劲。最后再分享一个小技巧如果你经常创建类似结构的项目可以把初始化之后要改的配置项比如 manifest.json 里的 appid 替换、pages.json 里的页面注册整理成一个 checklist每次新建项目按清单走一遍五分钟就能完成项目初始化既不会漏也不会慌。