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

也是有给微信小程序打交道好久了，终于是完结这一篇博文。小程序这个功能 已经成为了应用分发的重要形态，微信小程序，支付宝小程序，百度小程序，抖音小程序等。尤其是 微信小程序，凭借着微信庞大的用户数量、以及轻量级的使用体验以及无需下载即可使用的优势，已经成为了许多企业和个人开发者的首选平台。同时，跨平台开发框架的兴起，也让开发者不再需要为单一平台重复开发！

uni-app 基于 Vue.js，能够做到“一套代码，多端运行”，支持发布到 H5、iOS、Android 以及各大主流小程序平台（微信、支付宝、抖音、快手等）。在实际需求中，开发者往往会优先选择 微信小程序 作为第一个目标平台，这个是显而易见的，因为它的市场体量&用户基数最大

but，很多初学 uni-app 的同学在开发小程序时，往往会混淆几个概念：

运行（Run）
发布（Build）
发行（Release）

这三个环节虽然都出现在开发工具（如 HBuilderX、微信开发者工具）中，但它们所处的阶段、目的和作用完全不同。

有些同学在项目还没开发完成时就盲目去“发布”，结果遇到大量报错。
也有人在“运行”阶段误以为已经上线，却发现用户根本无法访问。
还有人因为“发行”流程理解不到位，导致多次被微信官方审核驳回。

so，本文将系统地从概念、使用方法、流程、注意事项到实战案例，完整解析 uni-app 在开发微信小程序时的 运行 → 发布 → 发行 全流程，帮助开发者厘清思路，避免走弯路。

阅读完本文，你将能够清晰回答以下问题：

运行、发布、发行分别在什么阶段使用？
它们之间的区别和联系是什么？
在实际项目中，应该如何正确使用这三种操作？
开发、调试、上线各阶段会遇到哪些常见问题，又该如何解决？

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

在正式进入操作流程之前，我们必须先彻底理解“运行、发布、发行”三个环节的差异。很多新手开发者遇到的坑，往往都是因为 概念不清 导致的。下面我们逐一拆解。

2.1 运行（Run）

定义：
运行指的是在开发阶段，把你的 uni-app 代码实时编译并运行在某个平台的模拟器或真机上，以便于进行调试和预览。

特点：

不会生成最终可交付的产物。
编译速度快，适合频繁调试。
支持 H5 运行、微信开发者工具模拟运行、真机扫码预览。
仅供开发者自己测试使用，不会对最终用户开放。

使用场景：

新建页面后，快速查看布局效果是否正确。
调试 API 调用，例如 uni.request 请求接口是否正常。
校验交互逻辑是否符合预期。

类比：
运行就好比写文档时的“预览模式”，你在写一篇文章，可以随时点击预览按钮看看排版效果，但这并不是最终印刷的书籍。

2.2 发布（Build）

定义：
发布指的是将 uni-app 源代码编译、打包成 目标平台的小程序代码包，例如微信小程序代码结构（app.json、pages/、utils/ 等）。

特点：

会生成可导入微信开发者工具的产物目录，通常在 dist/build/mp-weixin 下。
一旦发布完成，你就可以使用微信开发者工具来进一步调试。
发布阶段的产物，已经基本符合微信小程序的运行环境要求。

使用场景：

当项目开发到一定程度，需要在微信小程序的真实环境里调试。
在发布前进行打包，保证目录和配置符合小程序规范。

类比：
发布就像把 Word 文档导出为 PDF 文件。此时它已经是可以交付的格式，但还没有真正交到出版社印刷。

2.3 发行（Release / 上传上线）

定义：
发行是指将发布生成的微信小程序代码，通过微信开发者工具上传到 微信公众平台后台，并提交审核，审核通过后才可以对用户开放使用。

特点：

是真正意义上的上线过程。
包括上传代码、填写版本号与描述、提交审核、发布上线。
一旦审核通过并发布，用户就可以在微信内搜索或扫码访问你的程序。

使用场景：

项目开发完成，准备正式上线给用户使用。
需要提交新功能版本，更新已上线的小程序。

类比：
发行就像把 PDF 文件交给出版社印刷、上架，用户才能真正买到并阅读。

2.4 三者的对比总结

对比项	运行（Run）	发布（Build）	发行（Release）
所处阶段	开发调试	开发完成后，生成代码包	最终上线
面向对象	开发者自己	微信开发者工具	终端用户
产物	临时编译结果	微信小程序代码目录	上线小程序
工具依赖	HBuilderX / 模拟器	HBuilderX + 微信开发者工具	微信开发者工具 + 微信公众平台
是否用户可见	❌	❌	✅
常见问题	依赖未配置、接口调试失败	路径错误、包体积超限	审核驳回、版本发布延迟

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

前面我们已经明确了“运行”的概念：运行 = 开发阶段的实时预览与调试。这一阶段主要帮助开发者快速查看页面布局、调试接口逻辑、发现 bug。下面我们从实操角度详细解析。

3.1 创建并初始化项目

在 HBuilderX 中创建一个 uni-app 项目：

打开 HBuilderX → 菜单栏选择 文件 → 新建 → 项目。
选择 uni-app 模板（官方自带 Hello uni-app 示例项目，适合新手练习）。
填写项目名称、存放路径。
点击“创建”，生成项目结构。

默认项目目录结构：

├── pages/                 # 页面存放目录
│   ├── index/index.vue    # 首页
│   └── about/about.vue    # 示例页面
├── static/                # 静态资源目录
├── manifest.json          # 应用配置文件
├── pages.json             # 页面路由配置
├── uni.scss               # 公共样式文件
└── main.js                # 入口文件

关键点：

pages.json 控制页面路由和导航栏。
manifest.json 控制平台差异化配置（如微信小程序 AppID）。
每个页面是一个 .vue 文件，符合 Vue 单文件组件规范。

3.2 运行到浏览器（H5 端）

操作路径：运行 → 运行到浏览器 → Chrome。

特点：

可以直接在浏览器中查看页面效果。
支持浏览器开发者工具调试（F12）。
适合调试基础页面逻辑、样式布局。

注意：

H5 端和小程序端的 API 有一定差异，比如 window、document 只在 H5 有效。
跨域问题（CORS）在 H5 调试时会出现，但在小程序运行时不会。

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

操作路径：运行 → 运行到小程序模拟器 → 微信开发者工具。

前提：

必须安装微信开发者工具，并在 HBuilderX 中配置路径。
需要在 manifest.json → 小程序配置 中填写 AppID（测试阶段可用体验 AppID）。

效果：

HBuilderX 会自动编译生成 /unpackage/dist/dev/mp-weixin 目录。
打开微信开发者工具后，能直接看到小程序的模拟效果。
可以真机扫码预览，更接近最终体验。

3.4 真机运行（扫码调试）

在微信开发者工具中，点击预览按钮，会生成二维码。

使用微信扫码，即可在真机上运行当前项目。
适合验证机型兼容性（如 iOS 和 Android 的表现差异）。

3.5 常见运行问题

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

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

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

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

4.1 配置 `manifest.json`

manifest.json 是发布前必须配置的文件，里面决定了生成小程序的核心信息。

重点配置项：

应用标识
- AppID（微信小程序必须填写真实 AppID，否则无法上传发行）。
应用图标
- 用于小程序图标显示（建议 1024x1024 尺寸）。
权限配置
- 是否使用定位、摄像头、相册等权限。
分包加载
- 大型项目必须用分包（微信要求主包 ≤ 2MB，分包 ≤ 20MB）。

4.2 执行发布操作

操作路径：发行 → 小程序微信（微信开发者工具）。

效果：

HBuilderX 会进行编译，生成小程序项目目录。
默认存放位置：/unpackage/dist/build/mp-weixin。

生成后的目录结构类似：

dist/build/mp-weixin/
├── app.json
├── pages/
├── static/
├── utils/
└── project.config.json

这些就是符合微信小程序规范的代码文件，可以直接导入微信开发者工具。

4.3 导入到微信开发者工具

打开微信开发者工具 → 点击“导入项目”。
选择路径：dist/build/mp-weixin。
填写 AppID。
导入后即可看到小程序效果。

关键点：

导入时必须使用和 manifest.json 中一致的 AppID，否则上传时会报错。
如果只是测试，可以使用“无 AppID”模式，但不能发行。

4.4 调试与测试

在微信开发者工具中，可以进行以下操作：

模拟器运行 → 检查 UI 是否正常。
预览 → 真机扫码查看效果。
调试面板 → 打印日志、查看网络请求。

4.5 常见发布问题

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

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

经过“运行 → 发布”阶段，我们的项目已经完成了本地调试和产物生成。接下来，最重要的就是把项目发行上线，让真实用户能够在微信里使用。发行 = 上传代码 + 提交审核 + 发布上线。

5.1 上传代码

上传代码的工具是 微信开发者工具，而不是 HBuilderX。
操作步骤：

打开微信开发者工具，导入我们在 dist/build/mp-weixin 下生成的小程序代码。
在工具界面右上角，点击上传按钮。
填写以下信息：
- AppID：必须和微信公众平台注册的小程序一致。
- 版本号：例如 1.0.0。
- 版本描述：简要说明更新内容，如“首个上线版本”或“优化商品详情页”。
点击确认上传，等待完成。

上传后，代码会存放到 微信公众平台后台 → 版本管理 → 开发版本。

5.2 提交审核

上传成功后，还需要提交审核，审核通过后才能发布上线。

操作步骤：

登录微信公众平台。
进入 开发管理 → 开发版本，找到刚上传的版本。
点击 提交审核。
填写以下信息：
- 小程序类目：必须与小程序功能一致（比如“电商平台”不能填“资讯类”）。
- 标签与简介：用于审核和用户搜索展示。
- 体验者信息：可添加测试人员，便于上线前体验。
如果涉及特殊类目（医疗、教育、金融），需要上传相应的资质证书。

5.3 审核结果

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

5.4 上线后的版本管理

微信公众平台提供了多版本管理功能：

开发版本
- 仅开发者和体验者可见。
体验版
- 可供内测团队使用，但普通用户无法访问。
审核版
- 提交审核后生成，等待微信官方审核。
线上版
- 审核通过并发布的版本，面向所有用户。

5.5 灰度发布与流量控制

微信支持 灰度发布，也就是逐步放量上线：

可以设置部分用户先体验新版本。
如果发现 bug，可以快速回退到旧版本。
避免新版本 bug 全量影响所有用户。

5.6 常见发行问题

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

✅ 小结：
发行是 最后一步，它决定了用户能否真正使用你的项目。流程一般是：

上传代码 → 提交审核 → 审核通过 → 发布上线 → 用户可见

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

到这里，我们已经完整走完了 运行 → 发布 → 发行 的三大环节。为了防止开发者混淆，我们再做一次整体梳理。

6.1 阶段差异

运行（Run）：开发阶段，主要是调试和预览。
发布（Build）：开发完成后，生成小程序代码包。
发行（Release）：将代码上传审核，正式上线用户可见。

6.2 工具差异

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

6.3 面向对象差异

运行：开发者。
发布：测试团队（在小程序环境下调试）。
发行：终端用户。

6.4 产物差异

运行：临时调试结果。
发布：小程序代码包（dist/build/mp-weixin）。
发行：审核通过的小程序，用户可访问。

6.5 类比总结

运行 = 预览文档：开发者自己看效果。
发布 = 导出 PDF：生成可交付文件，但还没上架。
发行 = 印刷上架：用户才能真正购买和使用。

6.6 总结表格

对比项	运行（Run）	发布（Build）	发行（Release）
阶段	开发调试	编译生成产物	上线交付
面向对象	开发者	测试人员	最终用户
工具	HBuilderX / 模拟器	HBuilderX + 微信开发者工具	微信开发者工具 + 微信公众平台
产物	临时结果	小程序目录	审核上线小程序
是否用户可见	❌	❌	✅

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

光讲概念和流程还不够，我们来做一个实战案例，把 运行 → 发布 → 发行 三个阶段完整串起来。假设我们要开发一个 商品展示小程序，功能包括：

首页展示商品列表
商品详情页
购物车功能（本地存储）
联系客服按钮

7.1 项目需求分析

目标：

面向零售商，帮助他们快速上线一个小程序店铺。
功能尽量简单，突出商品展示。

用户流程：

打开小程序 → 首页看到商品列表 → 点击进入详情 → 加入购物车 → 查看购物车 → 联系客服购买。

7.2 项目初始化

打开 HBuilderX → 新建项目 → 选择 uni-app 模板。
目录结构生成后，修改 pages.json，定义页面路由：

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页"
      }
    },
    {
      "path": "pages/detail/detail",
      "style": {
        "navigationBarTitleText": "商品详情"
      }
    },
    {
      "path": "pages/cart/cart",
      "style": {
        "navigationBarTitleText": "购物车"
      }
    }
  ]
}

7.3 开发首页（商品列表）

<template>
  <view class="container">
    <view v-for="item in products" :key="item.id" class="product" @click="goDetail(item.id)">
      <image :src="item.image" class="product-img"></image>
      <text class="product-title">{{ item.name }}</text>
      <text class="product-price">￥{{ item.price }}</text>
    </view>
  </view>
</template>

<script>
export default {
  data() {
    return {
      products: [
        { id: 1, name: 'T恤', price: 99, image: '/static/tshirt.png' },
        { id: 2, name: '牛仔裤', price: 199, image: '/static/jeans.png' }
      ]
    }
  },
  methods: {
    goDetail(id) {
      uni.navigateTo({
        url: `/pages/detail/detail?id=${id}`
      })
    }
  }
}
</script>

7.4 商品详情页

<template>
  <view class="container">
    <image :src="product.image" class="detail-img"></image>
    <text class="detail-title">{{ product.name }}</text>
    <text class="detail-price">￥{{ product.price }}</text>
    <button type="primary" @click="addToCart">加入购物车</button>
  </view>
</template>

<script>
export default {
  data() {
    return {
      product: {}
    }
  },
  onLoad(query) {
    const id = query.id
    // 模拟请求
    const products = [
      { id: 1, name: 'T恤', price: 99, image: '/static/tshirt.png' },
      { id: 2, name: '牛仔裤', price: 199, image: '/static/jeans.png' }
    ]
    this.product = products.find(p => p.id == id)
  },
  methods: {
    addToCart() {
      let cart = uni.getStorageSync('cart') || []
      cart.push(this.product)
      uni.setStorageSync('cart', cart)
      uni.showToast({ title: '已加入购物车', icon: 'success' })
    }
  }
}
</script>

7.5 购物车页

<template>
  <view class="container">
    <view v-for="item in cart" :key="item.id" class="cart-item">
      <text>{{ item.name }} - ￥{{ item.price }}</text>
    </view>
    <button type="default" open-type="contact">联系客服</button>
  </view>
</template>

<script>
export default {
  data() {
    return {
      cart: []
    }
  },
  onShow() {
    this.cart = uni.getStorageSync('cart') || []
  }
}
</script>

7.6 运行阶段

在 HBuilderX 中选择 运行 → 运行到小程序模拟器 → 微信开发者工具。
调试首页、详情页、购物车逻辑是否正常。
使用真机扫码体验购物车功能。

7.7 发布阶段

打开 HBuilderX → 菜单栏 发行 → 小程序微信（微信开发者工具）。
生成目录 dist/build/mp-weixin。
打开微信开发者工具 → 导入目录 → 填写 AppID。
检查 UI、接口、逻辑是否与需求一致。

7.8 发行上线

在微信开发者工具点击上传，填写版本号 1.0.0 和描述“首个上线版本”。
登录微信公众平台 → 提交审核。
审核通过后点击发布 → 用户可搜索访问小程序。

✅ 小结：
通过本案例，我们完整演示了从 开发 → 运行调试 → 发布编译 → 发行上线 的全过程。实际项目中会更复杂，但思路相同。

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

在实际开发和上线过程中，开发者经常会遇到各种问题。下面我们按照阶段来总结常见坑点和解决方案。

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：审核被拒

常见原因：
1. 类目不符（比如“游戏类”代码放在“工具类”类目下）。
2. 页面含有广告、虚假描述。
3. 涉及医疗、教育、金融却未提供资质。
解决：根据驳回原因修改代码/资料，重新提交审核。

问题 3：用户访问报错“域名未备案”

原因：小程序接口域名必须备案并启用 HTTPS。
解决：检查域名备案状态，启用 SSL 证书。

问题 4：上线后发现 bug

解决：微信支持 回退版本 或 灰度发布，可快速修复问题。

常见问题集中在三个方面：

运行阶段 → 环境配置问题。
发布阶段 → 资源路径、包体积问题。
发行阶段 → 审核规范、域名备案问题。

只要把这三类问题提前规避，上线流程就会顺畅很多。

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

经过前面章节的详细解析与案例演示，相信大家对 uni-app 在微信小程序上的运行、发布与发行全流程 已经有了较为清晰的理解。
然而，真正的开发往往比文档复杂得多，以下是结合社区经验、企业项目实践总结出的最佳实践，帮助你少踩坑、提升效率。

9.1 代码结构与模块划分

保持清晰的目录结构
- 建议按照业务模块划分 pages/ 子目录，例如：
```
pages/
  ├─ home/       首页
  ├─ user/       用户相关
  ├─ order/      订单相关
  └─ settings/   设置
```
- 避免所有页面堆在 pages/ 根目录，后期难以维护。
公共组件独立化
- 可复用的 UI 或逻辑（如底部导航栏、表单组件、上传组件）放在 components/ 目录下。
- 这样发布或运行时，任何改动只需维护一份代码。

9.2 开发阶段的运行技巧

推荐使用微信开发者工具真机预览
- HBuilderX 的运行仅用于快速验证，最终还是要在微信小程序环境中测试。
- 尤其是支付、地图、蓝牙、订阅消息等 API，必须在真机上才能体验完整效果。
开启自动编译
- 在 HBuilderX 勾选「保存文件自动编译」，可以减少手动点击运行的时间。
- 对于大型项目，建议配合「仅编译修改文件」提升效率。
mock 数据调试
- 在开发早期，后端接口可能尚未完成。
- 建议使用 mock/ 文件夹存放模拟数据，避免因接口缺失而影响运行。

9.3 发布阶段的最佳实践

严格控制代码包体积
- 微信小程序 主包 ≤ 2MB，整体 ≤ 20MB。
- 对大体积资源（图片、视频）应上传到 CDN 或云存储，运行时动态加载。
使用分包加载
- 对于功能复杂的小程序，合理划分业务模块为多个分包，可以减少首屏加载时间。
- 示例：
```
subPackages: [
  {
    root: "pages/order/",
    pages: ["list", "detail"]
  }
]
```
版本号管理
- 发布时建议使用语义化版本号（如 1.2.0）。
- 每次打包记录版本与 Git 提交号，方便问题追溯。

9.4 发行阶段的最佳实践

上传前彻底自测
- 微信审核通常只允许提交 2~3 次，频繁驳回会延误上线进度。
- 因此建议内部先完成功能覆盖测试，避免低级 bug。
审核描述要清晰
- 审核提交时的「版本说明」要写明新增功能点、涉及的页面。
- 如果涉及支付、用户数据收集，要确保有相关资质。
灰度发布
- 对于大型项目，可以使用微信公众平台的「灰度发布」功能，先让一部分用户体验，逐步放量，降低风险。

9.5 团队协作与版本控制

Git 分支管理
- 开发分支（develop）、测试分支（test）、主分支（master）清晰区分。
- 发布版本前应打 tag（如 v1.0.0）。
持续集成（CI/CD）
- 可使用 uni-app CLI + GitHub Actions / Jenkins，实现自动化构建。
- 一旦代码合并到主分支，就自动触发打包并上传到微信小程序。