通过HBuilderX发布微信小程序操作指南

创创小搭官方阅读约 17 分钟

使用 HBuilderX 和 uni-app 框架，把小程序代码编译发行并提交到微信公众平台审核上线

截至 2026 年 8 月 · 全国 · HBuilderX 与微信开发者工具版本

开始之前

在开始发布前，请确认以下四项准备物已就绪：

微信小程序账号与 AppID
具体要求：已在微信公众平台注册小程序账号，并取得wx开头的 AppID
DCloud 开发者账号
具体要求：已在 DCloud 开发者中心注册并登录账号
安装核心软件
具体要求：已安装 HBuilderX（推荐 App 开发版）与微信开发者工具（稳定版）
已备案的接口域名
具体要求：后端 API 服务必须使用支持 HTTPS 协议且已完成 ICP 备案的域名

一、账号注册与准备

发布微信小程序需要使用两个账号：微信公众平台账号（用于小程序管理与上架）和 DCloud 开发者账号（用于 HBuilderX 云端编译与 AppID 托管）。

微信小程序账号这一侧，默认你已经注册完毕，并已在微信公众平台【设置】→「基本设置」→「帐号信息」里拿到wx开头的 AppID（3.2 配置manifest.json时要填进去）。下面只讲 DCloud 这一侧的准备。

1.1 注册 DCloud 开发者账号

使用 HBuilderX 编译 uni-app 项目及调用云服务时，需要登录 DCloud 账号。

1
浏览器访问 DCloud 开发者中心：https://dev.dcloud.net.cn。

DCloud 开发者中心注册入口

1
点击【注册】，选择用手机号或邮箱注册，填写用户名与密码。

DCloud 账号注册表单

1
根据注册方式完成验证：手机注册需补充验证邮箱，邮箱注册需补充验证手机号。

DCloud 邮箱验证通知

DCloud 手机验证通知

1
完成手机与邮箱双重验证后，账号即可正常使用。

DCloud 账号验证成功

1.2 解决 HBuilderX 项目 AppID 归属问题

如果打开的项目来自他人且当前 DCloud 账号没有该项目的权限，编译时会被系统拦截。处理方法如下：

1
在 HBuilderX 中打开项目根目录下的manifest.json文件。
2
进入【基础配置】标签页，找到「DCloud AppID」这一行。
3
点击右侧【重新获取】按钮，系统会自动生成一个属于当前登录账号的新 AppID。

HBuilderX 重新获取 DCloud AppID

二、软件安装与环境配置

2.1 安装与登录 HBuilderX

1
访问 DCloud 官网下载 HBuilderX（建议选择内置 uni-app 编译器的 App 开发版）。
2
解压压缩包至非系统盘目录（如D:\HBuilderX），运行HBuilderX.exe。
3
点击 HBuilderX 左下角【未登录】，输入 DCloud 账号与密码完成登录。

HBuilderX 账号登录

2.2 安装必要插件

如果使用的是标准版 HBuilderX，需要手动补齐编译器插件：

1
点击菜单栏【工具】→【插件安装】。
2
找到「uni-app 编译」与「SCSS/SASS 编译」插件，点击【安装】。

2.3 安装与配置微信开发者工具

1
访问微信开发者工具官网下载稳定版（Stable Build）并完成安装。
2
打开微信开发者工具，使用管理员或开发者权限的微信号扫码登录。
3
开启服务端口：在微信开发者工具中点击【设置】→「安全设置」，找到「服务端口」并将开关切为【开启】。
⚠️ 高危点：服务端口未开启会导致调起失败
如果未在微信开发者工具中开启服务端口，HBuilderX 执行运行或发行指令时将无法自动打开微信开发者工具，并报错“服务端口未开启”。
1
配置运行路径：在 HBuilderX 中点击菜单栏【工具】→【设置】→「运行配置」，找到「微信开发者工具路径」，填入安装目录下的可执行文件路径：
•
Windows 路径示例：C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat
•
macOS 路径示例：/Applications/wechatwebdevtools.app/Contents/MacOS/cli

三、创建与配置项目

3.1 新建 uni-app 项目

1
在 HBuilderX 中点击菜单栏【文件】→【新建】→【项目】。
2
选择「uni-app」，输入项目名称（使用英文，如my-miniapp），选择存储路径与 Vue3 模板，点击【创建】。

3.2 配置 manifest.json

1
在 HBuilderX 中双击打开项目根目录下的manifest.json。
2
点击左侧【微信小程序配置】标签页。
3
在「微信小程序 AppID」输入框中，粘贴在微信公众平台获取的 AppID。
4
勾选「ES6 转 ES5」、「上传代码时样式自动补全」与「上传代码时自动压缩」。
{
"mp-weixin": {
"appid": "wx1234567890abcdef",
"setting": {
"urlCheck": false,
"es6": true,
"postcss": true,
"minified": true
},
"usingComponents": true
}
}

3.3 配置服务器域名

如果小程序存在网络请求，必须在微信公众平台配置合法域名：

1
登录微信公众平台，进入【开发】→【开发管理】→【开发设置】。
2
在「服务器域名」区域点击【修改】，填入后端的合法域名：
•
「request合法域名」：必须为https://协议且已完成 ICP 备案
•
「uploadFile合法域名」与「downloadFile合法域名」按需配置
1
保存设置。在开发调试阶段，可在微信开发者工具【详情】→「本地设置」中勾选「不校验合法域名」进行临时测试。

四、开发调试与发行编译

4.1 运行到微信小程序模拟器

1
在 HBuilderX 中打开项目文件，点击菜单栏【运行】→【运行到小程序模拟器】→【微信开发者工具】。
2
HBuilderX 将自动进行增量编译，并调用微信开发者工具打开项目预览。
3
在 HBuilderX 中修改代码并保存（Ctrl+S），模拟器将实时更新预览。

4.2 执行发行编译

开发完成后，必须使用生产模式进行发行编译，移除调试信息并进行代码压缩。

1
在 HBuilderX 中点击菜单栏【发行】→【小程序-微信】。

HBuilderX 发行菜单入口

1
在弹出的对话框中确认「项目名称」与「微信小程序 AppID」无误，点击【发行】。

HBuilderX 发行微信小程序对话框

1
等待控制台提示编译完成。发行产物输出至项目目录下的unpackage/dist/build/mp-weixin/路径。

4.3 把发行产物导入微信开发者工具

发行编译只生成代码目录，微信开发者工具不会自动把它列成项目。此前用【运行到小程序模拟器】打开过的那个项目，指向的是开发产物unpackage/dist/dev/mp-weixin/，不能拿它上传。首次发行后手动导入一次，之后每次重新发行，开发者工具会自动刷新这个已存在的项目。

1
打开微信开发者工具，在左侧【小程序】页点击右上角【导入】。项目卡片区域中间那个+是新建空白项目，不要点。

微信开发者工具「小程序」页右上角的【导入】入口

1
在弹出的文件夹选择框中一路点进项目目录下的unpackage → dist → build → mp-weixin，点击【选择文件夹】。停在它的上级build会提示未找到 app.json。

选择 build 目录下的 mp-weixin 文件夹

1
「项目名称」默认填的是文件夹名mp-weixin，改成一个带发行标识的名字（如xxx小程序-发行），与运行模拟器生成的开发项目区分开。
2
「AppID」会自动读取该目录下project.config.json里的appid，确认与manifest.json中填写的一致。
3
「后端服务」按项目实际情况选：后端部署在自己的服务器上就选「不使用云服务」，用微信云开发的才选「微信云开发」并勾选底部的服务条款。
4
点击【创建】，项目导入完成。

导入项目对话框，填好项目名称、目录与 AppID

4.4 代码包体积检查与优化

1
在微信开发者工具右上角点击【详情】→「基本信息」。
2
查看「代码包大小」，确认是否超出上限：
•
主包/单个分包限制：≤ 2 MB
•
总包体积限制：≤ 20 MB
1
超出限制时，将static/目录中的大图抽离至 CDN 网络地址，或在pages.json中配置subPackages分包加载。

五、上传代码与体验版测试

5.1 上传代码到微信后台

1
确认当前操作的是上面导入的那个发行项目，目录为unpackage/dist/build/mp-weixin/。窗口标题显示的就是导入时填的项目名称，认名字最稳妥——开发项目与发行项目界面完全一样，传错了不会有任何报错提示。
2
点击微信开发者工具右上角【上传】按钮。

微信开发者工具上传按钮

1
在弹出的对话框中填写版本号（如1.0.0）和项目备注（描述本次更新要点）。

填写版本号与项目备注

1
点击【上传】，等待状态栏提示“代码上传成功”。

代码上传成功提示

5.2 微信后台查看开发版本

1
登录微信公众平台，进入【管理】→【版本管理】。
2
在「开发版本」列表中，可查看到刚刚上传的版本记录。

微信公众平台开发版本列表

5.3 设置体验版与真机测试

1
在「开发版本」列表中找到目标版本，点击右侧【选为体验版】。
2
进入【管理】→【成员管理】，在「体验成员」区域点击【添加成员】，输入测试人员微信号。
3
将体验版二维码发送给测试人员，在 iOS 与 Android 真机上测试页面跳转、接口请求与授权功能。

六、提交审核与正式上线

6.1 提交审核操作

1
在微信公众平台【管理】→【版本管理】的「开发版本」中，点击【提交审核】。
2
勾选已阅读审核须知，点击【下一步】。
3
填写审核信息：配置主功能页面、上传 1-5 张小程序运行截屏、提供测试账号与密码（若需登录）、填写补充说明。
4
点击【提交审核】。审核状态可在【版本管理】的「审核版本」区域查看，通常需 1-7 个工作日。

6.2 配置隐私保护指引

如果小程序涉及获取用户头像、昵称、手机号或地理位置，必须在提审前配置隐私协议：

1
登录微信公众平台，进入【设置】→【服务内容声明】→「用户隐私保护指引」。
2
点击【更新】，按页面提示选择收集的信息类型及用途并保存。

6.3 正式发布上线

1
审核通过后，管理员微信将收到审核通过通知。
2
登录微信公众平台，进入【管理】→【版本管理】。
3
在「审核版本」中找到通过审核的版本，点击【发布】。
4
选择发布模式（全量发布或分阶段灰度发布），点击确认。
5
发布完成后，用户即可在微信中搜索小程序名称或扫描小程序码访问。

七、发布后运维与常见报错排查

7.1 版本回退

如果新版本上线后出现重大故障，可快速回退至上一版本：

1
进入微信公众平台【管理】→【版本管理】。
2
在「线上版本」区域点击【版本回退】。
⚠️ 高危点：版本回退每日限一次且仅支持退回上一版
版本回退操作会将线上代码直接替换为上一已发布版本，一天内仅能操作一次，且无法连续回退多个版本。

7.2 常见报错排查

点击运行没反应
常见原因：微信开发者工具未开服务端口或路径配置错误解决办法：检查微信开发者工具【设置】→「安全设置」中「服务端口」是否开启；检查 HBuilderX 运行配置中的cli.bat路径是否准确
编译提示 appid 不合法
常见原因：manifest.json中 AppID 填写错误或不匹配解决办法：检查manifest.json中mp-weixin.appid是否存在空格或错别字，确认已在微信公众平台绑定该账号
报错未找到 app.json
常见原因：微信开发者工具导入的项目路径错误解决办法：确认微信开发者工具打开的路径指向unpackage/dist/dev/mp-weixin/（开发模式）或unpackage/dist/build/mp-weixin/（发行模式）
接口报错 url not in domain list
常见原因：请求域名未配置在微信后台域名白名单中解决办法：在微信公众平台【开发设置】中添加https://接口域名；开发阶段可在微信开发者工具【详情】→「本地设置」中勾选「不校验合法域名」

小结

通过 HBuilderX 发布微信小程序的关键在于环境联调与编译分发的分工协作：HBuilderX 负责 uni-app 代码的开发与生产发行编译，微信开发者工具负责项目预览、代码上传与端口对接，微信公众平台负责版本托管、体验版测试、审核与正式发布。在日常迭代中，只需重复“HBuilderX 发行编译 → 微信开发者工具上传 → 微信后台提审发布”的标准流程即可。

AI 助手