应直接使用HBuilderX创建uni-app项目，因其对多端编译支持最稳定，内置调试、真机运行、云打包等能力，而CLI方式已逐步弱化维护，易出现插件注册、生命周期不触发、路由配置失效、真机调试失败等问题。
直接用 HBuilderX 就行，别折腾 CLI 或 Vue CLI 创建项目——它对 uni-app 的多端编译支持最稳，且内置调试、真机运行、云打包等关键能力，手动配环境反而容易出兼容问题。
为什么不用 npm install -g @vue/cli + vue create？
uni-app 官方早已将核心工具链深度集成进 HBuilderX，而 CLI 方式生成的项目（比如 vue create -p dcloudio/uni-preset-vue my-project）在 2025 年后已逐步弱化维护。实际踩坑点包括：
-
uni-app插件在 CLI 项目中需手动注册，onLaunch等生命周期可能不触发 - 微信小程序平台编译时提示
Cannot find module '@dcloudio/uni-mp-weixin'，需额外安装且版本难对齐 - H5 端路由模式（
pages.json中"h5": { "router": { "base": "/" } }）在 CLI 项目里默认不生效，要改 webpack 配置 - 真机调试依赖 HBuilderX 的代理服务，CLI 启动的 dev server 无法直连手机
HBuilderX 安装与首次配置要点
下载最新稳定版（当前推荐 v3.8.16+），不是“Alpha”或“Beta”测试版——后者虽新但常有云打包失败、条件编译失效等问题。
安装后必须做三件事：
- 启动时登录
dcloud.io账号（未登录会导致真机调试弹窗被拦截、云函数上传失败） - 进入
设置 → 外观与行为 → 编辑器 → 文件编码，把默认编码设为UTF-8（否则中文路径下static图片引用会 404） - 勾选
工具 → 插件安装 → App真机运行和uni-app App调试（这两个插件不显示在插件市场，必须从菜单手动启用）
创建项目时避开模板陷阱
HBuilderX 新建项目时，“模板类型”别选带 uView、uni-ui 或“电商”“IM”字样的预设模板——它们强行注入大量非标准目录和全局 mixin，后期升级 @dcloudio/uni-app 版本时极易报错 TypeError: Cannot read property 'xxx' of undefined。
正确做法是：
- 选择
uni-app→默认模板（Vue 3）或默认模板（Vue 2）（根据团队技术栈定，别混用） - 项目名用纯英文+下划线，避免空格或中文（否则微信开发者工具导入时报
invalid project.config.json） - 创建后立刻检查根目录是否存在
manifest.json和pages.json，缺一不可——没有manifest.json的项目无法发布到 App 或小程序
Node.js 和命令行工具只是辅助，不是必需
你确实需要装 Node.js（LTS 版本，如 v20.18.0），但仅用于：
- 运行
npm run build:mp-weixin这类自定义构建脚本（极少用） - 本地起 mock 服务（
json-server）或调试接口 - 安装
cnpm加速插件市场组件下载（npm install -g cnpm --registry=https://r.cnpmjs.org）
千万别为了“显得专业”去全局安装 @dcloudio/uni-cli 或 uni-app CLI 包——HBuilderX 自带编译器不读这些，装了反而可能干扰 node_modules 解析顺序，导致 import { ref } from 'vue' 报错。
真正卡住人的从来不是装不装得上，而是 manifest.json 里 appid 没填、pages.json 里页面路径写错斜杠方向、或者真机调试时忘了在手机上打开“USB 调试”并点击“始终允许”。这些细节比工具选择重要得多。
