1.4 开发环境搭建

1.4 开发环境搭建

本节导读：机制与历史就位后，本节把罗盘握进手里：完成 HBuilderX 与 CLI 两条工具链的安装配置，打通微信开发者工具联动与浏览器预览，并跑通第一个多端项目。环境差异是新手卡壳的高发区，本节的检查清单按症状给出对策。

开一个新 uni-app 工程前，先决定走哪条工具链，因为这决定了后续所有命令的样子。HBuilderX 路线：官方 IDE 内置编译器，点按钮即可运行到各端，适合快速起步与小团队；CLI 路线：用命令行脚手架创建工程，编译管线暴露在依赖清单里，适合要接入自建流水线、有定制构建需求的团队。两条路线的工程目录结构一致，可以互相迁移，但编译配置的写法不同，团队务必二选一作为主链路，另一条仅作备份。

HBuilderX 路线：五步跑通

安装 HBuilderX（选标准版即可，插件按需联网安装），然后依次执行：新建项目，选择 uni-app 模板并选定 Vue 版本；等待依赖索引完成；点击菜单里的运行到浏览器，选一个 Chrome 分支，HBuilderX 会起本地服务并自动打开页面；运行到微信开发者工具时，首次会提示配置微信开发者工具的安装路径，并要求在其设置里开启服务端口；运行到真机则用数据线连接手机，在运行菜单里选择设备。整个过程不需要手写任何构建配置，编译产物默认输出在工程侧的 unpackage 目录里。

微信开发者工具的联动有一个高频卡点：必须在其"设置 → 安全"里打开服务端口，否则 HBuilderX 拉不起工具，报错通常只说"启动失败"，不指明原因。此外，微信开发者工具里要先登录并打开"不校验合法域名"选项，本地联调后端接口才不会被拦。

CLI 路线：命令行创建与运行

CLI 路线把同样的流程搬进终端，以 Vue3 加 vite 的工程为例：

# 创建工程（vite 线，Vue3）
npx degit dcloudio/uni-preset-vue#vite my-shop

# 安装依赖
cd my-shop && npm install

# 各端开发运行
npm run dev:h5                  # 浏览器端，默认输出到本地服务
npm run dev:mp-weixin           # 微信小程序，产物在 dist/dev/mp-weixin
npm run dev:app-plus            # App 端，需配合 HBuilderX 或自定义基座运行

# 各端发布构建
npm run build:h5
npm run build:mp-weixin
​

小程序端的开发流是"编译器吐产物、开发者工具吃产物"：dev:mp-weixin 会持续把编译产物写到 dist 目录，你在微信开发者工具里导入这个产物目录（不是源码目录），之后边改源码边等编译刷新。理解这条数据流向，能省掉大量"改了没生效"式的迷惑。

第一个多端页面

用默认模板的首页改成积分商城的雏形，验证环境链路：

<template>
  <view class="home">
    <text class="title">会员商城</text>
    <button type="primary" @click="onCheck">{{ btnText }}</button>
  </view>
</template>

<script>
export default {
  data() {
    return { btnText: '签到领积分' };
  },
  methods: {
    onCheck() {
      // #ifdef H5
      this.btnText = 'H5 端已签到';
      // #endif
      // #ifndef H5
      this.btnText = '客户端已签到';
      // #endif
      uni.showToast({ title: '签到成功', icon: 'success' });
    }
  }
};
</script>

<style>
.home { padding: 40rpx; }
.title { font-size: 40rpx; font-weight: bold; }
</style>
​

把它分别跑在浏览器与微信开发者工具里，点击按钮观察文案差异——如果两端文案不同且提示框都正常弹出，说明条件编译与 uni API 链路都已就绪。这个十行的小页面，就是全册所有示例的最小验证环境。

两个真实故障的定位过程

环境问题难缠在症状与病因相距甚远，把两个典型案例的定位过程摆出来，比罗列一百条注意事项更能建立手感。案例一：运行到微信开发者工具一直失败。 背景是新同事入职第一天装完全套工具，点运行后弹窗提示启动失败。排查从链路本身入手：HBuilderX 拉起微信开发者工具走的是工具开放的服务端口，逐环验证——工具能否手动打开（能），HBuilderX 里配置的工具路径是否存在（存在），工具的安全设置里服务端口是否开启（没开）。打开服务端口后一次成功。这个案例的教训是：启动失败类报错先怀疑"工具间通道"，而不是编译本身。

案例二：H5 预览一切正常，微信端白屏。 背景是商城首页引入了一个浏览器专属的图表库，源码里直接顶层调用。定位方法是看编译产物：微信端产物里该调用原样存在，运行时找不到浏览器对象直接抛错，页面整体渲染中断。解决分两步——把初始化包进条件编译只在 H5 端执行，小程序端换用兼容的 canvas 方案。它印证了 1.1 节的判断：编译期不报错不代表各端都能跑，白屏的根源常常是"某端独享的全局对象"。

两个案例共用一套定位次序：先分清是"编译没过"还是"编译过了但运行期炸"，前者查工具链与语法，后者查平台专属能力。环境阶段养成这个分流习惯，后面几章的调试会顺畅得多。

环境检查清单

装完不要急着写业务，先过一遍清单。逐项对照，比出了问题再排查省一个上午：

💡 一个省心的习惯：每接手一台新机器，先用上一节的十行页面在 H5 与微信两端各跑一遍再开工。环境问题在这一步暴露的成本最低。

小结

• 工具链二选一：HBuilderX 路线点按钮、CLI 路线跑命令，工程结构一致但构建配置体系不同；
• 小程序开发流是"编译器吐产物、工具吃产物"，微信开发者工具里导入的应是 dist 产物目录；
• 服务端口、合法域名、基础库版本是微信端三大高频卡点，清单化检查最省时间；
• 十行签到页面是全册的最小验证环境，环境异动时先拿它回归。

环境就位，下一节把工程目录摊开看：每个文件夹在编译时扮演什么角色。