先明确你要用哪种方式安装
uni-app模板的安装方式主要分两类：HBuilderX可视化创建，以及CLI命令行拉取。两者最终生成的项目结构基本一致，区别在于依赖管理和后续升级习惯。如果你不熟悉Node.js，优先选HBuilderX；如果团队用Git协作、需要定制构建流程，CLI更合适。
方式一：HBuilderX创建模板项目
打开HBuilderX，点击顶部菜单「文件」→「新建」→「项目」。在弹出的窗口中选择「uni-app」类型，然后从模板列表里挑一个，比如默认模板、uni-ui模板或登录页模板。
注意两点：一是项目名称不要用中文或空格；二是存放路径不要选在系统盘根目录，避免权限问题。点击创建后，HBuilderX会自动生成目录并安装内置依赖。
如果你下载的是别人分享的模板压缩包，不要直接解压到HBuilderX项目目录里。正确做法是：先解压到任意位置，再通过「文件」→「导入」→「从本地目录导入」，选中模板根目录。导入后检查根目录下是否有manifest.json和pages.json，这两个文件是uni-app项目的标志。
方式二：CLI命令行安装模板
确保本机已安装Node.js 14以上版本，然后执行：
npx degit dcloudio/uni-preset-vue#vite my-project
或者用vue-cli方式：
vue create -p dcloudio/uni-preset-vue my-project
进入项目目录后安装依赖：
cd my-project
npm install
如果是Vue3+Vite模板，依赖安装完成后运行npm run dev:h5即可在浏览器预览。运行到微信小程序则用npm run dev:mp-weixin，然后用微信开发者工具打开dist/dev/mp-weixin目录。
安装后必须检查的三个配置
第一，manifest.json中的应用标识。 用HBuilderX打开时，点「基础配置」重新获取uni-app标识；用CLI则手动填入appid。缺少appid会导致无法真机运行。
第二，pages.json的页面路径。 模板自带的页面路径必须与实际文件位置一致。如果移动了页面文件，记得同步修改pages数组，否则启动白屏。
第三，依赖版本对齐。 CLI方式下，@dcloudio/uni-app、@dcloudio/uni-h5等包版本要一致。出现Cannot find module时，先删除node_modules和package-lock.json，再重新npm install。
常见报错与处理
报错：npm install 卡在某个包。 换用淘宝镜像npm config set registry https://registry.npmmirror.com，再重试。
报错：HBuilderX提示“未安装插件”。 在工具→插件安装里，安装“scss/sass编译”和“uni-app编译”两个插件，重启后生效。
运行到微信小程序时报“app.json未找到”。 说明编译未完成，检查是否执行了dev:mp-weixin，且微信开发者工具打开的是dist下的对应目录，而不是项目根目录。
最后一步：跑通再改
模板安装完成后，先不要急着改业务代码。用默认页面运行一次，确认H5端、小程序端至少有一个能正常显示。能跑通，说明安装环节没有遗留问题，后续替换页面和组件才有稳定基础。
