小程序开发环境从零搭好

很多人第一次做小程序，卡住的地方不是写代码，而是环境没搭顺：工具装好了却登录不上、依赖装完了却跑不起来、真机预览一片空白。这篇文章把小程序开发环境拆成几个部分，按顺序讲清楚每个环节该做什么、容易忽略什么。

一、开发环境由哪几块组成

一个完整的小程序开发环境，通常包含四层：

• IDE 层：微信开发者工具，负责编码、编译、调试、预览、上传。
• 运行时层：Node.js 与包管理器，支撑 npm 依赖、构建脚本、本地 mock 服务。
• 后端层：云开发环境或自建服务端，决定数据存哪、接口怎么调。
• 协作层：Git 仓库、代码规范工具、环境变量配置。

四层里任何一层缺失，都会在后续开发中反复制造问题。建议一开始就按这个结构把目录和账号准备好。

二、微信开发者工具的正确安装方式

去微信官方文档的下载页获取稳定版，不要用来路不明的安装包。安装时注意两点：

• 安装路径尽量不含中文和空格，避免后续构建脚本路径解析出错。
• 首次启动后用小程序管理员或开发者的微信扫码登录，普通体验账号无法上传代码。

登录后新建项目时，需要填写 AppID。没有 AppID 可以先用测试号，但测试号不支持云开发和部分开放能力，正式项目务必提前在公众平台注册并拿到 AppID。

项目配置里的关键项

project.config.json 是项目级配置，团队协作时应当提交到 Git。常见需要关注的字段：

{
  "appid": "wx**************",
  "projectname": "demo",
  "miniprogramRoot": "miniprogram/",
  "setting": {
    "es6": true,
    "enhance": true,
    "postcss": true,
    "minified": true,
    "urlCheck": true
  }
}

miniprogramRoot 用于指定小程序源码目录，配合 npm 构建时尤其重要；urlCheck 打开后，开发阶段请求非备案域名会被拦截，本地联调可临时关闭，但提交前要恢复。

三、Node.js 与 npm 构建

如果项目使用 npm 包（如 UI 组件库、工具函数），需要先安装 Node.js。建议选择 LTS 版本，并在项目根目录执行：

npm init -y
npm install --save-dev miniprogram-api-typings
npm install --save @vant/weapp

安装完成后，在开发者工具中点击「工具 - 构建 npm」，工具会把 node_modules 中符合小程序规范的包处理到 miniprogram_npm 目录。这里有两个细节：

• 每次新增或升级依赖后都要重新构建 npm，否则页面里 require 会报模块找不到。
• miniprogram_npm 是构建产物，通常不提交到仓库，由 CI 或本地构建生成。

四、云开发环境与自建后端的取舍

云开发适合快速起步：在开发者工具中开通后，直接获得数据库、云函数、存储和 CDN，省去服务器与备案。初始化代码如下：

// app.js
App({
  onLaunch() {
    if (!wx.cloud) {
      console.error('请使用 2.2.3 或以上的基础库以使用云能力')
      return
    }
    wx.cloud.init({
      env: 'your-env-id',
      traceUser: true
    })
  }
})

如果业务需要复杂事务、已有后端体系或对数据合规有要求，就选自建服务端。此时开发环境要额外准备：本地接口地址、开发域名白名单、跨域与 HTTPS 证书。开发者工具支持「不校验合法域名」选项，但只能在开发阶段使用，真机预览和上线都必须走已配置的合法域名。

五、真机调试与多环境管理

模拟器通过不代表真机通过。真机调试建议固定流程：

1. 在工具中点击「预览」，用手机微信扫码。
2. 打开「真机调试」，观察 console 与 network 面板。
3. 重点验证登录态、网络请求、文件上传和授权弹窗。

多环境（开发、测试、生产）建议用配置文件区分，而不是手动改代码：

// config/index.js
const env = 'dev'
const configs = {
  dev: { baseUrl: 'https://dev.api.example.com' },
  prod: { baseUrl: 'https://api.example.com' }
}
module.exports = configs[env]

配合构建脚本在打包时替换 env，能显著减少「测试环境地址被带上线」这类问题。

六、团队协作的补充配置

• 用 Git 管理代码，.gitignore 中排除 node_modules、miniprogram_npm、本地私有配置文件。
• 接入 ESLint 或 Prettier，在提交前统一格式，避免多人协作时 diff 噪音。
• 把 AppID、云环境 ID、接口域名整理进项目 README，新成员照着文档就能跑起来。
• 给开发者工具设置固定的代码片段与快捷键，长期看能省下不少重复操作。

环境搭建的目标不是「能打开工具」，而是「任何人拉下代码，按文档执行几步就能跑通预览和真机调试」。把这一点做到，后面的开发效率才有保障。