环境搭建与项目初始化：Node.js与CLI工具安装、使用uni-app创建项目、项目目录结构解析、HBuilderX与微信开发者工具联动

好，咱们正式开始动手了。这一章我带你走一遍环境搭建的全流程。说实话，很多新手在这步就卡住了——不是装错版本，就是工具链没配好。别急，我踩过的坑，你一个都不用再踩。

Node.js 安装：选对版本很重要

uni-app 依赖 Node.js 运行环境。我个人习惯用 LTS 版本，稳定，不折腾。

安装完成后，打开终端验证一下：

node -v
npm -v

能看到版本号，说明装好了。嗯，这里要注意：如果你之前装过旧版本，建议先卸载干净。我在项目中遇到过因为 Node 版本太低导致 uni-app 脚手架报错的情况，排查了半天才发现是版本问题。

CLI 工具安装：用 @dcloudio/uni-cli-i18n

uni-app 官方提供了 CLI 工具。我个人推荐用 @dcloudio/uni-cli-i18n 这个包，它支持国际化，后续做多语言也方便。

全局安装命令：

npm install -g @dcloudio/uni-cli-i18n

装完之后，试试看能不能用：

uni --version

如果提示命令找不到，别慌。大概率是 npm 全局路径没加到系统环境变量里。Windows 用户检查一下 %APPDATA%\npm，Mac/Linux 用户检查 /usr/local/lib/node_modules 是否在 PATH 中。

使用 uni-app 创建项目

环境配好了，咱们来创建第一个项目。运行：

uni create my-first-app

你会看到交互式命令行，让你选择模板。我个人习惯选「默认模板」，它最干净，没有多余的东西。如果你想快速看到效果，也可以选「Hello uni-app」模板。

创建完成后，进入项目目录：

cd my-first-app
npm install

安装依赖这一步，有时候会卡住。为什么？因为网络问题。我建议用淘宝镜像：

npm install --registry=https://registry.npmmirror.com

装完之后，项目就准备好了。你可以用 uni serve 启动开发服务器，不过我更推荐用 HBuilderX 来跑，后面会讲。

项目目录结构解析

打开项目文件夹，你会看到这样的结构：

my-first-app/
├── pages/          # 页面文件夹
│   └── index/      # 首页
│       ├── index.vue
│       ├── index.scss
│       └── index.json
├── static/         # 静态资源
├── uni_modules/    # 插件市场下载的模块
├── uni.scss        # 全局样式变量
├── App.vue         # 应用入口组件
├── main.js         # 应用入口JS
├── manifest.json   # 应用配置（名称、图标、权限等）
├── pages.json      # 页面路由配置
└── uni.config.js   # 构建配置

我重点说几个你一定会频繁打交道的文件：

• pages.json：所有页面的路由、导航栏、窗口样式都在这里配。说白了，它就是小程序的「路由器」。
• manifest.json：应用的元信息。比如你要改应用名称、图标、AppID，都来这里。
• App.vue：全局逻辑。比如应用启动时检查登录状态，我习惯写在这里。

你想想看，这个结构是不是很清晰？页面、配置、资源各归其位。我在项目中见过有人把所有代码都塞进一个文件里，那维护起来简直是噩梦。

HBuilderX 与微信开发者工具联动

这是最爽的一步。HBuilderX 是 DCloud 官方 IDE，对 uni-app 支持最好。下载安装后，打开项目文件夹。

首先，你要在 HBuilderX 里配置微信开发者工具的路径：

1. 点击菜单栏「工具」→「设置」→「运行配置」
2. 找到「微信开发者工具路径」，选择你安装的 wechat_devtools.exe（或 .app）
3. 保存

配置好后，在 HBuilderX 顶部工具栏选择「运行」→「运行到小程序模拟器」→「微信开发者工具」。第一次运行会有点慢，因为要编译整个项目。之后就好了，改代码保存后自动刷新。

我记得第一次用这个联动功能时，觉得太方便了。以前做小程序，改一行代码要手动切回开发者工具点编译，现在全自动了。

常见问题与解决

问题	原因	解决办法
运行报错「找不到模块」	依赖没装全	重新执行 npm install
微信开发者工具没反应	服务端口未开启	在微信开发者工具设置中开启服务端口
编译后页面空白	pages.json 路由配置错误	检查 pages 数组中的路径是否正确
HBuilderX 无法识别 CLI 项目	项目不是 HBuilderX 创建	在 HBuilderX 中「导入项目」即可

嗯，到这里环境就搭好了。你可以在微信开发者工具里看到你的第一个 uni-app 页面。虽然现在只是个空白页，但别急，下一章我们就开始写真正的业务代码了。

最后说一句：环境搭建这一步，一次配好，后面省心。我见过太多人因为环境问题浪费大量时间。按照上面的步骤来，应该不会出问题。如果还有疑问，欢迎交流。