hbuilderx新建uni-app项目需四步：启动后等菜单完全就绪，再“文件→新建→项目”；必须选“uni-app项目”模板，项目名用英文小写加短横线，路径不含中文和空格；推荐选“默认模板(vue3)”；创建后确认项目树含app.vue、pages.json等关键文件即成功。
直接创建就能跑，但卡在“新建项目”这一步的，90%是因为没等菜单就点、模板选错、路径含中文或项目名用了大写——这些不是bug，是HBuilderX初始化机制和uni-app工程约束共同决定的硬性条件。
启动后必须等菜单栏完全就绪再操作
HBuilderX首次启动或升级后，界面加载分两阶段：先是UI框架，再是插件与菜单注册。如果左上角还没出现完整的“文件→编辑→视图→项目→工具→运行→调试→窗口→帮助”，此时点“文件→新建→项目”会灰掉或无响应。
- 等待右下角状态栏消失“未就绪”字样，或观察菜单栏是否可点击（非灰色）
- 若菜单仍不可用，不要反复点击，等10–20秒；强行操作会导致后续npm install静默失败
- 确认就绪后再进入新建流程，否则整个项目结构可能缺
pages.json或node_modules
模板选错会导致Vue版本错配或缺失核心配置
“uni-app项目”模板本身不等于可用项目——它只是容器，真正决定能否编译的是右侧模板选项。选错模板，轻则首页白屏，重则vue无法识别setup语法。
- 新手推荐选
默认模板(Vue3)：支持<script setup></script>、组合式API，且无冗余示例代码 - 别选“Hello uni-app”做业务起点：它把所有组件都塞进
index.vue，删不干净易引发样式/逻辑冲突 - 避坑点：
uni-ui项目模板自带完整UI库，但体积大、启动慢；仅当你明确要用uni-badge、uni-list等组件时才选 - 务必取消勾选“启用 TypeScript”初学阶段：JSX/TS类型提示在HBuilderX里支持不稳定，容易触发
Cannot find module 'vue'
项目名和路径的字符限制是硬性规则，不是建议
HBuilderX内部调用npm init和unpackage构建链，路径和名称一旦含非法字符，会在微信开发者工具中报Invalid project root path，或导致pages.json路由注册失败。
- 项目名只能用小写字母+短横线，例如
my-shop-app；MyShopApp、my shop app、我的商城全部不行 - 项目路径不能含中文、空格、括号，也不能是C盘根目录（如
C:\）；推荐D:\uni-projects\my-shop-app - 路径含中文时，HBuilderX可能跳过
npm install步骤，node_modules为空，但界面上不报错——这是最隐蔽的失败场景
创建后验证项目是否真成功，只看三个文件
右下角“正在初始化项目”消失≠项目建好。很多用户误以为创建完成，结果运行时报pages.json not found，其实是初始化中途被中断或路径不合法导致依赖未装全。
- 打开左侧项目树，确认存在且可展开：
App.vue、main.js（或main.ts）、pages.json、manifest.json - 双击打开
pages/index/index.vue，检查是否只剩标准三块：<template></template>、<script setup></script>、<style scoped></style>；若有大量示例代码，说明模板选错或初始化残留 - 资源管理器里确认
node_modules文件夹大小超过20MB（首次创建通常50MB+），否则就是npm install没走完
最容易被忽略的是：项目创建后不要立刻改pages.json或删static目录——HBuilderX在后台仍在写入基础配置，前30秒内任何手动修改都可能导致路由表损坏。等编辑器右下角彻底安静、且能正常高亮<template></template>标签，才算真正落地。
