uni-app 微信小程序开发全流程指南

第一章 前言

随着小程序功能的普及，它已成为应用分发的重要形态，包括微信小程序、支付宝小程序、百度小程序、抖音小程序等。其中，微信小程序凭借庞大的用户基数、轻量级体验和无需下载的优势，成为许多开发者的首选平台。同时，跨平台开发框架如 uni-app 的兴起，让开发者无需为不同平台重复开发。

uni-app 基于 Vue.js，支持“一套代码，多端运行”，可发布到 H5、iOS、Android 及主流小程序平台。在实际开发中，微信小程序常作为首选目标，因其市场体量和用户基数最大。

然而，许多 uni-app 初学者在开发小程序时，容易混淆几个关键概念：运行（Run）、发布（Build）和发行（Release）。这三个环节虽都出现在开发工具中，但阶段、目的和作用完全不同。例如，有些开发者在项目未完成时就盲目“发布”，导致报错；或在“运行”阶段误以为已上线，用户无法访问；或因“发行”流程理解不足，审核多次驳回。

因此，本文将系统解析 uni-app 开发微信小程序的运行、发布、发行全流程，从概念、方法、流程到实战案例，帮助开发者厘清思路，避免弯路。

阅读本文后，您将能清晰回答：

1. 运行、发布、发行分别在什么阶段使用？
2. 它们之间的区别和联系是什么？
3. 在实际项目中，如何正确使用这三种操作？
4. 开发、调试、上线各阶段的常见问题及解决方案。

第二章 核心概念解析：运行、发布、发行

在正式进入操作流程前，必须彻底理解运行、发布、发行三个环节的差异。许多新手开发者遇到的问题，往往源于概念不清。

2.1 运行（Run）

运行指在开发阶段，将 uni-app 代码实时编译并运行在模拟器或真机上，以便调试和预览。其特点是不会生成最终可交付产物，编译速度快，适合频繁调试，支持 H5 运行、微信开发者工具模拟运行和真机扫码预览，仅供开发者测试使用，不对最终用户开放。使用场景包括新建页面后查看布局效果、调试 API 调用如 uni.request 请求接口、校验交互逻辑等。类比而言，运行就像写文档时的预览模式，可随时查看效果，但非最终成品。

2.2 发布（Build）

发布指将 uni-app 源代码编译打包成目标平台的小程序代码包，如微信小程序代码结构。其特点是生成可导入微信开发者工具的产物目录，通常在 dist/build/mp-weixin 下，发布后可在微信开发者工具中进一步调试，产物基本符合小程序环境要求。使用场景是当项目开发到一定程度，需在真实小程序环境中调试，或打包保证目录和配置符合规范。发布就像把 Word 文档导出为 PDF 文件，已是可交付格式，但尚未上架。

2.3 发行（Release / 上传上线）

发行指将发布生成的微信小程序代码，通过微信开发者工具上传到微信公众平台后台，提交审核后对用户开放使用。其特点是真正意义上的上线过程，包括上传代码、填写版本号与描述、提交审核、发布上线，一旦审核通过，用户即可在微信内搜索或扫码访问。使用场景是项目开发完成准备正式上线，或提交新功能版本更新已上线小程序。发行就像把 PDF 文件交给出版社印刷上架，用户才能真正使用。

2.4 三者的对比总结

第三章 uni-app 项目运行（Run）的详细使用方法

运行是开发阶段的实时预览与调试，帮助开发者快速查看页面布局、调试接口逻辑、发现 bug。下面从实操角度详细解析。

3.1 创建并初始化项目

在 HBuilderX 中创建 uni-app 项目：

1. 打开 HBuilderX → 菜单栏选择“文件 → 新建 → 项目”。
2. 选择 uni-app 模板（如 Hello uni-app 示例项目）。
3. 填写项目名称、存放路径。
4. 点击“创建”，生成项目结构。

默认项目目录结构包括 pages/、static/、manifest.json、pages.json、uni.scss 和 main.js。关键点：pages.json 控制页面路由和导航栏，manifest.json 控制平台差异化配置如微信小程序 AppID，每个页面是 .vue 文件，符合 Vue 单文件组件规范。

3.2 运行到浏览器（H5 端）

操作路径：运行 → 运行到浏览器 → Chrome。特点是可以直接在浏览器中查看页面效果，支持浏览器开发者工具调试，适合调试基础页面逻辑和样式布局。注意：H5 端和小程序端的 API 有差异，如 window、document 只在 H5 有效；跨域问题在 H5 调试时会出现，但小程序运行时不会。

3.3 运行到微信开发者工具（小程序模拟器）

操作路径：运行 → 运行到小程序模拟器 → 微信开发者工具。前提是必须安装微信开发者工具，并在 HBuilderX 中配置路径；需在 manifest.json → 小程序配置中填写 AppID（测试阶段可用体验 AppID）。效果是 HBuilderX 自动编译生成 /unpackage/dist/dev/mp-weixin 目录，打开微信开发者工具后能看到小程序模拟效果，可真机扫码预览更接近最终体验。

3.4 真机运行（扫码调试）

在微信开发者工具中点击预览按钮生成二维码，使用微信扫码即可在真机上运行项目，适合验证机型兼容性如 iOS 和 Android 的表现差异。

3.5 常见运行问题

1. 运行时报错：未找到微信开发者工具：检查 HBuilderX 中的配置路径：工具 → 设置 → 小程序路径配置。
2. 接口调试失败：微信小程序端必须在“微信公众平台 → 开发 → 开发管理 → 开发设置”里配置合法域名。
3. 运行结果和实际发布效果不一致：H5 模拟和小程序端有差异，必须在“运行到小程序模拟器”里测试才准确。

运行阶段的核心目标是快速调试，不要误以为运行成功等于上线成功，它更像是开发过程中的即时反馈工具。

第四章 uni-app 发布（Build）的流程与细节

当开发工作基本完成或需要在小程序环境下做更真实调试时，就进入发布阶段。发布指编译源码生成目标平台产物。

4.1 配置 manifest.json

manifest.json 是发布前必须配置的文件，决定生成小程序的核心信息。重点配置项包括应用标识如 AppID（微信小程序必须填写真实 AppID，否则无法上传发行）、应用图标建议 1024x1024 尺寸、权限配置如是否使用定位、摄像头、相册等，以及分包加载（大型项目必须用分包，微信要求主包 ≤ 2MB，分包 ≤ 20MB）。

4.2 执行发布操作

操作路径：发行 → 小程序微信（微信开发者工具）。效果是 HBuilderX 进行编译，生成小程序项目目录，默认存放位置：/unpackage/dist/build/mp-weixin。生成后的目录结构包括 app.json、pages/、static/、utils/ 和 project.config.json，这些是符合微信小程序规范的代码文件，可直接导入微信开发者工具。

4.3 导入到微信开发者工具

1. 打开微信开发者工具 → 点击“导入项目”。
2. 选择路径：dist/build/mp-weixin。
3. 填写 AppID。
4. 导入后即可看到小程序效果。关键点：导入时必须使用和 manifest.json 中一致的 AppID，否则上传时报错；如果只是测试，可使用“无 AppID”模式，但不能发行。

4.4 调试与测试

在微信开发者工具中可进行模拟器运行检查 UI、预览真机扫码查看效果、调试面板打印日志和查看网络请求。

4.5 常见发布问题

1. 路径错误：常见原因是图片或静态资源路径写错，建议统一用相对路径 @/static/xxx。
2. 包体积超标：主包最大 2MB，分包最大 20MB，解决方法包括合理拆分分包、大文件放到云存储。
3. 依赖插件未配置：如果使用第三方小程序插件，需在 manifest.json → 小程序配置 → 插件中声明。
4. 兼容性问题：不同平台 API 存在差异，如 navigator 在 H5 可用但在小程序端不可用，需用 uni 统一 API。

第五章 uni-app 项目发行（Release）上线流程

经过运行和发布阶段，项目已完成本地调试和产物生成，接下来发行上线让真实用户使用。发行包括上传代码、提交审核、发布上线。

5.1 上传代码

上传代码使用微信开发者工具，操作步骤：

1. 打开微信开发者工具，导入 dist/build/mp-weixin 下生成的小程序代码。
2. 在工具界面右上角点击上传按钮。
3. 填写 AppID（必须和微信公众平台注册的小程序一致）、版本号如 1.0.0、版本描述如“首个上线版本”。
4. 点击确认上传，等待完成。上传后代码存放到微信公众平台后台 → 版本管理 → 开发版本。

5.2 提交审核

上传成功后需提交审核，操作步骤：

1. 登录微信公众平台。
2. 进入开发管理 → 开发版本，找到刚上传的版本。
3. 点击提交审核。
4. 填写小程序类目（必须与功能一致）、标签与简介、体验者信息。如果涉及特殊类目如医疗、教育、金融，需上传相应资质证书。

5.3 审核结果

• 审核通过：版本进入“审核通过”状态，点击发布即可上线，用户可搜索或扫码访问。
• 审核不通过：微信审核团队给出驳回理由，常见原因包括功能与申报类目不一致、涉及违规内容如敏感词或侵权资源、没有提供必需资质。修改代码或资料后重新上传并提交审核。

5.4 上线后的版本管理

微信公众平台提供多版本管理：开发版本仅开发者和体验者可见；体验版可供内测团队使用但普通用户无法访问；审核版提交审核后生成等待审核；线上版审核通过并发布面向所有用户。

5.5 灰度发布与流量控制

微信支持灰度发布，即可逐步放量上线，设置部分用户先体验新版本，发现 bug 可快速回退到旧版本，避免新版本 bug 全量影响所有用户。

5.6 常见发行问题

1. 无法上传代码：检查 AppID 是否与公众平台一致，manifest.json 是否填写正确。
2. 审核反复驳回：检查类目选择是否符合小程序内容，确保 UI 规范不含广告违规元素。
3. 包体积超限：主包不能超过 2MB，解决方法包括拆分分包、使用云开发托管资源。
4. 用户访问报错：检查微信后台“开发设置 → 合法域名”是否配置正确。

发行是最后一步，决定用户能否真正使用项目，流程一般是：上传代码 → 提交审核 → 审核通过 → 发布上线 → 用户可见。

第六章 运行、发布、发行的关键区别再总结

为防混淆，再次整体梳理运行、发布、发行的关键区别。

6.1 阶段差异

运行是开发阶段调试和预览；发布是开发完成后生成小程序代码包；发行是上传审核正式上线用户可见。

6.2 工具差异

运行使用 HBuilderX 和微信开发者工具（调试用）；发布使用 HBuilderX 编译打包；发行使用微信开发者工具和微信公众平台。

6.3 面向对象差异

运行面向开发者；发布面向测试团队在小程序环境下调试；发行面向终端用户。

6.4 产物差异

运行产生临时调试结果；发布产生小程序代码包；发行产生审核通过的小程序用户可访问。

6.5 类比总结

运行像预览文档开发者自己看效果；发布像导出 PDF 生成可交付文件但未上架；发行像印刷上架用户才能真正使用。

6.6 总结表格

第七章 实战案例：从 0 到 1 完成一个小程序

通过实战案例完整串联运行、发布、发行三个阶段。假设开发一个商品展示小程序，功能包括首页展示商品列表、商品详情页、购物车功能（本地存储）、联系客服按钮。

7.1 项目需求分析

目标是为零售商快速上线小程序店铺，功能简单突出商品展示。用户流程：打开小程序 → 首页看到商品列表 → 点击进入详情 → 加入购物车 → 查看购物车 → 联系客服购买。

7.2 项目初始化

在 HBuilderX 新建 uni-app 项目，修改 pages.json 定义页面路由，包括首页、商品详情页、购物车页。

7.3 开发首页（商品列表）

使用 Vue 模板展示商品列表，每个商品包括图片、名称、价格，点击商品跳转到详情页。

7.4 商品详情页

展示商品详细信息，包括图片、名称、价格，加入购物车按钮使用本地存储保存商品。

7.5 购物车页

从本地存储读取购物车商品列表，显示商品名称和价格，提供联系客服按钮。

7.6 运行阶段

在 HBuilderX 中选择运行到小程序模拟器调试首页、详情页、购物车逻辑，使用真机扫码体验购物车功能。

7.7 发布阶段

在 HBuilderX 中发行到小程序微信生成代码包，导入微信开发者工具检查 UI、接口、逻辑是否一致。

7.8 发行上线

在微信开发者工具上传代码，填写版本号和描述，提交审核，审核通过后发布上线。通过本案例完整演示从开发到运行调试、发布编译、发行上线的全过程。

第八章 常见问题与解决方案

总结各阶段常见问题和解决方案。

8.1 运行阶段问题

• 问题1：运行时报错“未找到微信开发者工具路径”：解决是在 HBuilderX → 工具 → 设置 → 小程序路径配置中正确填写微信开发者工具安装路径。
• 问题2：接口请求失败：原因是微信小程序必须在“开发设置 → 服务器域名”里配置合法域名，解决是确保后台 API 域名已添加并启用 HTTPS。
• 问题3：H5 模拟和小程序端效果不一致：原因是小程序不支持 window、document 等 Web API，解决是统一使用 uni.* API。

8.2 发布阶段问题

• 问题1：资源路径错误：解决是统一使用 @/static/xxx.png 或相对路径，避免绝对路径。
• 问题2：主包体积超限：微信要求主包 ≤ 2MB，解决是启用分包加载，把非首页页面拆分到子包。
• 问题3：插件调用失败：解决是在 manifest.json → 小程序配置 → 插件中声明插件 AppID 和版本号。

8.3 发行阶段问题

• 问题1：上传时报错“AppID 不一致”：检查 manifest.json 和导入微信开发者工具时填写的 AppID 是否一致。
• 问题2：审核被拒：常见原因包括类目不符、页面含有广告或虚假描述、涉及特殊类目未提供资质，解决是根据驳回原因修改代码或资料重新提交审核。
• 问题3：用户访问报错“域名未备案”：原因是小程序接口域名必须备案并启用 HTTPS，解决是检查域名备案状态启用 SSL 证书。
• 问题4：上线后发现 bug：解决是利用微信的回退版本或灰度发布功能快速修复。

常见问题集中在运行阶段的环境配置、发布阶段的资源路径和包体积、发行阶段的审核规范和域名备案，提前规避可让上线流程更顺畅。

第九章 最佳实践与经验总结

结合社区经验和企业项目实践总结最佳实践，帮助少踩坑提升效率。

9.1 代码结构与模块划分

保持清晰的目录结构，按业务模块划分 pages/ 子目录，避免所有页面堆在根目录。公共组件如 UI 或逻辑放在 components/ 目录下，便于维护。

9.2 开发阶段的运行技巧

推荐使用微信开发者工具真机预览，尤其是支付、地图等 API 需真机体验。开启自动编译如保存文件自动编译减少手动时间。在开发早期使用 mock 数据调试避免接口缺失影响。

9.3 发布阶段的最佳实践

严格控制代码包体积，微信小程序主包 ≤ 2MB，整体 ≤ 20MB，对大体积资源上传到 CDN 或云存储。使用分包加载减少首屏加载时间。版本号管理使用语义化版本号如 1.2.0，每次打包记录版本与 Git 提交号方便追溯。

9.4 发行阶段的最佳实践

上传前彻底自测，避免频繁审核驳回延误上线。审核描述清晰写明新增功能点和涉及页面，确保支付或数据收集有相关资质。利用灰度发布逐步放量降低风险。

9.5 团队协作与版本控制

使用 Git 分支管理如开发分支、测试分支、主分支清晰区分，发布版本前打 tag。持续集成可使用 uni-app CLI 和 GitHub Actions 或 Jenkins 实现自动化构建和上传。

9.6 总结：运行、发布、发行的黄金法则

运行要快保持高效调试；发布要稳代码结构清晰控制包体积；发行要慎测试全面审核材料准备充分。掌握这三点可显著提升开发效率降低踩坑概率。

第十章 结语

uni-app 作为成熟跨平台开发框架，简化了多端应用开发成本。在微信小程序平台上，开发者需理解并掌握运行、发布、发行的完整流程。本文系统解析了运行作为开发调试、发布生成代码包、发行上传审核上线的全过程，并通过实战案例和最佳实践提供指导。技术只是手段，产品才是目标，真正决定小程序价值的是解决用户痛点和提升用户体验。希望本文帮助开发者高效完成小程序开发与上线，祝开发顺利，小程序早日上线！