最常见原因是 Node.js 版本过低（需 ≥16.14.0）或 npm 镜像源不稳定；建议升级 Node、切回官方源、加 --offline 参数，选模板需匹配目标平台兼容性，并手动配置 project.config.json 与 uni_modules/uniCloud。
uni-app CLI 创建项目失败：npm create uni-app@latest 报错或卡住
最常见原因是 Node.js 版本过低或 npm 镜像源不稳定。uni-app 官方 CLI 要求 Node.js ≥ 16.14.0，低于这个版本会直接报 ERR_UNSUPPORTED_ESM_URL_SCHEME 或静默退出。
实操建议：
- 先运行
node -v确认版本，低于v16.14.0就升级（推荐用nvm管理） - 临时切回官方源：
npm set registry https://registry.npmjs.org/，再执行创建命令 - 如果卡在
fetching template，大概率是模板仓库（GitHub）被限流，可加--offline参数跳过远程校验：npx create-uni-app@latest myapp --offline - 不建议用
vue create或npm init vue@latest后手动加 uni-app 插件——结构不兼容，后续uni.getSystemInfoSync()等 API 会返回undefined
创建时选错模板类型：vue2 vs vue3 vs vue3-ts
不是“越新越好”。Vue 3 模板默认启用 Composition API + <script setup></script>，但微信小程序基础库 2.27.0 以下不支持 defineProps 的运行时推导，会导致编译报错 Cannot read property 'type' of undefined。
实操建议：
- 主攻微信小程序且需兼容低版本（如政务、企业微信场景），选
vue2模板更稳 - 用 Vue 3 时务必检查
project.config.json中的minPlatformVersion，微信平台至少设为"2.27.0" -
vue3-ts模板生成的shims-uni.d.ts里缺uni.showModal返回类型的定义，需手动补全，否则 TS 提示Property 'confirmText' does not exist - 所有模板生成后，立刻删掉
src/pages/index/index.vue里的onLoad示例代码——它在 Vue 3 +<script setup></script>下无法触发，容易误以为生命周期失效
npm run dev:mp-weixin 启动失败：找不到 project.config.json 或提示“未配置 appid”
CLI 创建的项目默认不生成微信开发者工具所需的配置文件，也不会预填 appid。这不是 bug，是设计使然——uni-app 不希望把敏感信息写死在代码里。
实操建议：
- 运行命令前，先手动在项目根目录创建
project.config.json，内容至少包含：{"appid": "wx1234567890", "description": "uni-app project", "setting": {"urlCheck": false}} - 若用 HBuilderX 导出过微信项目，注意它生成的
project.config.json里有"compileType": "miniprogram"，CLI 项目必须加上，否则真机调试白屏 - appid 必须是当前微信公众号后台已绑定的小程序 AppID，填错或未绑定，控制台会报
invalid appid，但错误信息藏在微信开发者工具「调试器 → Console」里，不在终端输出中 - 别在
package.json的scripts里硬编码 appid，应通过环境变量注入："dev:mp-weixin": "UNI_APPID=wx1234567890 vite --mode weixin"
创建完项目发现没有 uni_modules 目录或 uniCloud 相关文件
CLI 默认不初始化云开发和模块市场支持。uni-app 的 uni_modules 是独立于主项目结构的插件机制，uniCloud 则需要单独开通服务空间并初始化目录，不会随 create uni-app 自动创建。
实操建议：
- 要使用
uni_modules，需手动在项目根目录新建uni_modules文件夹，并确保vue.config.js或vite.config.ts中启用了对应解析器（Vue 3 项目需加uniModules: { enable: true }） - 启用
uniCloud前，先去 uniCloud 控制台 创建服务空间，再在项目根目录运行npx @dcloudio/uni-cloud-cli init，而不是直接复制别人项目里的cloudfunctions文件夹 - 很多教程说“创建项目时勾选 uniCloud”，那是 HBuilderX 图形界面的功能，CLI 命令行无此选项，强行添加会导致
uniCloud目录被忽略或上传失败
真正麻烦的不是创建动作本身，而是创建后没意识到：uni-app 的 CLI 和 HBuilderX 的项目结构、配置加载逻辑、甚至 node_modules 解析路径都不完全一致。一个在 HBuilderX 里能跑的项目，用 CLI 启动可能连 uni.getProvider 都返回空数组——因为少了 vue.config.js 里那一行 configureWebpack: { resolve: { alias: { '@dcloudio/uni-ui': 'uni-ui' } } }。
