企业官网建设流程全解析

先交代一下背景。我做前端开发有几年了，最近在用 uni-app 做一个微信小程序，需求很常见：首页要内嵌一个 H5 页面，这个 H5 是另一个团队维护的，里面有活动配置、长图文、跳转落地页，直接用小程序原生语法重写一遍成本太高，最快的路径就是 uniAPP 微信小程序通过 webview 跳转到其他网址。

一开始我也觉得，不就是放一个<web-view>标签、把链接塞进src里的事吗？可真把这条链路做完、提审、上线之后回头看，才发现这里面的门道比预想多得多：页面怎么写、域名怎么配、参数怎么传、两端怎么通信，每一个环节都有对应的坑。任何一个没注意，线上就可能出现白屏、跳转失败、“不支持打开非业务域名”这类事故。

这篇文章就按我实际做一遍的顺序，把 uni-app 微信小程序里使用 webview 跳转到外部网址的完整过程拆开讲。该给代码给代码，该给配置给配置，每一步都会说明为什么这么做。如果你正打算在小程序里嵌 H5，或者已经被域名校验报错折磨了一轮，这篇文章应该能帮你少走不少弯路。

1. 场景与方案选型：为什么非得用 webview

1.1 先搞清楚 webview 到底解决了什么问题

微信小程序本质上是一个封闭的运行时环境，它没有浏览器那种“输入网址直接访问”的能力。用户在小程序里看到的页面，要么是用 WXML、WXSS 写出来的原生页面，要么就是通过 webview 组件加载的 H5 网页。

现实需求里，我们经常需要把一个已经做好的网页塞进小程序里：可能是运营活动页、可能是用户协议、可能是第三方提供的报表页面，也可能是公司官网的一个子页面。如果这些都改用小程序原生语法重写，性价比很低，而且以后每次页面内容调整，都得在两边同步改一遍，维护成本直接翻倍。

webview 存在的意义，就是用最小的成本把整个网页原样呈现给用户，H5 的展示逻辑、交互方式、接口调用全部保持不变。对应到 uni-app 上，webview 被封装成了<web-view>组件，编译到微信小程序时，会直接映射成微信原生的web-view组件。

有一点要先记住：微信小程序里每个页面只能存在一个 webview 组件。你不可能在一个页面里塞两个<web-view>，更不能在 webview 页面上叠加另一个 webview，这在设计页面结构的时候就得提前想清楚。

1.2 对比过几种方案之后，为什么最后还是选了 webview

在决定用 webview 之前，我其实还对比过其他几种承载外部网页的方式，这里把结论放出来，方便你判断自己的场景是不是也适合这条路。

第一种方案，小程序里直接用导航 API 跳转到一个网址字符串。这个方案直接被否掉，因为小程序页面的跳转目标是本地注册的 page 路径，不是外面任意一个 URL。微信小程序没有开放“直接把用户带到某个外部网址”的原生跳转能力，除非你是从 webview 里的 H5 再往外跳，那又是另一套逻辑了。

第二种方案，用iframe。小程序里根本没有 iframe 的概念，原生组件列表里压根找不到它。这条路从一开始就不存在。

第三种方案，是去控制 H5 页面的域名，让它和小程序同源，减少跨域问题。这个方案听起来美好，实际落地会发现，小程序对 webview 的域名限制依然存在，而且代理链路非常长，还要维护额外的转发服务，只适合极少数内部系统场景，不适合通用业务。

所以最终可行且官方推荐的就是 webview。它一个组件解决页面加载、内容渲染、生命周期管理，还额外支持小程序和 H5 之间的消息通信。我们在项目中最终的方案就是新开一个 webview 页面，把 src 指向 H5 地址，其余全部交给 H5 自己处理。

我个人的体会是：技术方案的选定，真不是看它听起来多高级，而是看它能不能用官方支持的路线解决核心问题。webview 是微信官方提供的标准能力，文档齐全、相关的坑也有据可查，后期维护起来相对可控。如果你的需求就是“嵌入一个现成网页”，没有特殊理由，不要自己发明轮子。

1.3 什么情况下不适合用 webview

webview 不是万能的，动手之前先排查几个场景。

如果外部 H5 页面强依赖 cookie 会话，而小程序端和 H5 端又没法共享登录态，用户打开页面大概率是“未登录”状态。这种情况必须先做登录态打通，否则不要硬上 webview。

如果 H5 页面里集成了微信支付能力，webview 内的支付唤起是受限制的，尤其是指定业务域名之外的页面，支付流程基本走不通。这类需求还是回归小程序原生支付流程更稳妥。

如果 H5 页面在服务端设置了X-Frame-Options: DENY之类的防嵌套策略，或者做了严格的 User-Agent 校验，在小程序 webview 里加载时可能直接被拒绝展示。这个不是配置能解决的问题，需要联系 H5 那边单独处理。

在开始写代码之前，把这些场景过一遍，能省下后面非常大的返工成本。

2. uni-app 里 webview 的落地写法

2.1 页面搭建与组件写法

在 uni-app 项目里，我先新建了一个专门承载 webview 的页面，比如pages/webview/index.vue，模板部分核心就是一个<web-view>组件。直接上代码：

<template> <view class="webview-page"> <web-view :src="webUrl" @message="handleMessage"></web-view> </view> </template>

这里有几个细节必须说清楚。

第一，web-view建议写成成对标签，不要图省事写成自闭合的<web-view />。我在 uni-app 里就遇到过写成自闭合形式后，编译到微信小程序出现页面白屏的情况，改成<web-view></web-view>后一切正常。这种问题很隐蔽，报错也不明显，遇到白屏可以先检查这一条。

第二，webview 是原生组件，它的层级天然高于普通组件，在真机上会覆盖在当前页面的最上层。如果你需要在 webview 页面上叠加悬浮按钮、自定义提示条，普通的view是压不住它的。微信后来做了同层渲染，部分基础库版本里普通组件可以覆盖，但为了兼容老版本，稳妥做法还是用cover-view或者干脆把悬浮元素改成 H5 内部渲染。

第三，src对应的地址必须是https://开头。微信小程序的 webview 在线上环境中不会加载http://地址，开发工具里勾选了“不校验域名”时可以临时打开，但到了真机和线上一定会出问题。

2.2 动态拼接 URL 的正确姿势

大多数场景下，webview 要打开的网址不是写死的，它跟当前用户、当前活动 ID、推广渠道都有关系。所以通常的做法是在onLoad里把参数取出来，动态拼到 URL 上，再赋值给webUrl。

<script> export default { data() { return { webUrl: '' } }, onLoad(options) { const baseUrl = 'https://example.com/pages/activity' const activityId = options.id || 'default' const token = uni.getStorageSync('token') || '' this.webUrl = `${baseUrl}?id=${activityId}&token=${encodeURIComponent(token)}` } } </script>

这段代码里最容易被忽略的是encodeURIComponent。登录 token、用户昵称、JSON 字符串这些内容里经常包含&、=、#、+、中文字符，不编码直接拼到 URL 上，H5 那边拿到的参数大概率是错的。

我见过同事因为没做编码，token 里的+号被解析成空格，导致 H5 端接口鉴权全部失败。页面看起来明明能打开、URL 看起来也正常，但就是登录失效，排查了很久才发现是编码问题。这类问题肉眼很难发现，所以一定养成习惯：所有 query 参数都过一遍encodeURIComponent。

还有一个小细节：如果 H5 页面自身也依赖 hash 路由，小程序端拼接 URL 时尽量不要在 hash 后面乱加参数。hash 之后的内容是给 H5 路由自己解析的，小程序和 H5 共享的是整个 URL，乱拼参数很容易把 H5 的路由搞乱。真要用 hash 传参，也要确认 H5 那边能正常识别。

2.3 onLoad 执行时机与参数容错

小程序的onLoad在 webview 页面初始化时就会执行，此时options里已经带上了跳转时传入的参数。但页面的入口不一定只有小程序内部导航这一条路，还可能被扫码进入、被其它页面重定向进入，所以参数一定要做容错处理。

比如options.id可能不存在，直接取出来拼到 URL 里就变成?id=undefined，H5 那边拿到一个字符串"undefined"，如果接口校验严格，很可能直接报错。我的习惯是给参数写默认值，或者判断为空时丢弃这个参数。

另外一个需要留意的点是：不要在onShow里频繁修改webUrl。webview 的机制是只要src发生变化，整个网页就会重新加载。如果你在onShow里每次都对webUrl赋值，哪怕值没有变化，也可能触发一次 reload，用户从后台切回来就发现 H5 被强行刷新了，体验非常差。需要传参就在onLoad处理，需要刷新就明确告诉用户“正在刷新”并主动改一次 URL。

3. 业务域名校验：最容易被卡住的一关

3.1 为什么微信要卡业务域名

微信小程序对 webview 一个核心限制是：webview 只能打开已经配置到小程序后台“业务域名”列表里的网页。这个限制的初衷很明确——防止开发者用 webview 把用户带到任意外部站点，绕过小程序审核机制，比如嵌入广告、诱导链接、甚至一些不合规的内容。

这意味着什么？意味着你在本地敲代码的时候，URL 随便写都能在开发者工具里看到效果，但一旦上传体验版走线上环境，如果域名没有配置到业务域名白名单里，页面会直接打不开，并且弹出“不支持打开非业务域名”的提示。

很多第一次做 webview 的人，都会在这里卡一下。开发者工具里明明好好的，真机一跑就白屏，十有八九就是这个原因。

3.2 业务域名的完整配置流程

配置业务域名需要登录微信公众平台，进入“开发管理 - 开发设置 - 业务域名”进行设置。我走了一遍，完整流程如下：

第一步，准备好要内嵌的页面域名，比如https://activity.example.com。注意这个域名必须是已备案的域名，并且要支持 HTTPS 访问，这个没得商量。

第二步，下载官方提供的校验文件。微信后台会给你一个需要放置在服务器根目录下的校验文件，通常就是一段 TXT 文本文件，文件名类似UxJixxxxxxxxxx.txt这样的随机字符串。

第三步，把校验文件放到该域名对应的服务器根目录下，并确保通过https://activity.example.com/UxJixxxxxxxxxx.txt这个地址能够直接访问到文件内容。

第四步，回到微信公众平台，填入要校验的域名，点击保存。微信后台在保存时会去访问这个校验文件，校验通过后，域名就被加入白名单了。

这里有三个非常容易忽略的点。

第一个，如果同一个域名下面有不同路径，只要域名本身一样，就算已经配置。不需要为每一个路径单独配置业务域名。但example.com和api.example.com是两个不同的域名，必须分别添加。

第二个，配置完成后，开发者工具有时候不会立刻刷新配置。如果你在工具里编译后仍然提示域名未配置，先重新编译一次，或者退出工具重新打开，再确认后台配置是否保存成功。

第三个，业务域名配置是有修改次数限制的。频繁增删域名会很快消耗配额，后期想改都改不了。所以配置之前，最好先梳理清楚整个项目到底会涉及哪几个域名，一次性配置完，不要今天加一个、明天加一个。

3.3 开发阶段的临时放行

在开发阶段还没配置域名时，开发者工具右上角“详情 - 本地设置”里可以直接勾选“不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书”，这样本地就能打开任意网站地址，方便调试。

这只是开发环境的临时放行。真机预览时，如果把调试模式打开，同样可以临时不校验；一旦关闭调试，真机就恢复正常校验了。

这里对应着一个特别典型的坑：有些开发者在开发者工具里看过效果，觉得一切正常，结果一提交线上，用户端全部打不开。原因就是线上环境不认这个勾选。所以我的习惯是：本地能跑通只是第一步，必须走一遍“配置业务域名 + 体验版真机校验”的完整流程，确认域名校验已经通过，再走提审。这个问题在前端项目里几乎每个新接手 webview 的同事都会踩一次，提前记住了能省掉一整个下午的排查时间。

4. URL 传参与登录态处理

4.1 query 参数接收的基本写法

H5 页面通常跑在自己的服务器上，它不知道 webview 是从哪个小程序进来的，唯一能拿到上下文的地方就是 URL。所以小程序端要传给 H5 的数据，基本都是拼在 URL 的 query 参数上。

H5 端接收参数的方法很简单，如果 H5 用的也是 Vue：

const query = new URLSearchParams(location.search) const activityId = query.get('id') const token = query.get('token')

如果是原生 JS 或者其它框架，思路一样，就是解析location.search。只要参数名约定好、编码统一，传值就不会有问题。

这里要特别提醒：小程序端和 H5 端是不同团队或者不同人维护时，一定要把参数名、参数格式、编码规则都用文档固定下来。项目里最容易出现的情况是，小程序端传的是userId，H5 端读的是uid，对接时互相都不知道对方改了什么，最后靠看网络请求才定位到问题。

4.2 传复杂数据结构时的编码细节

如果你要传的不是简单字符串，而是一个对象或数组，千万不要图省事直接JSON.stringify后拼到 URL 上。对象里包含了{}"这些字符，直接拼上去会直接把 query 结构撑破，H5 端解析出来的参数是残缺的。

正确做法是先序列化，再整体编码一次：

const params = JSON.stringify({ id: 1, name: 'test', level: 'A' }) this.webUrl = `${baseUrl}?params=${encodeURIComponent(params)}`

H5 端接收时先decodeURIComponent还原原始字符串，再JSON.parse解析成对象。这一步编码和解码必须对称，否则传过去就是乱码。

我在实际项目中还遇到过一种情况：某些 H5 框架在解析完 query 后，会先做一次整体 decode，导致参数里的%被二次转义，出现双重解码问题。这个问题没有通用解法，最好的办法是 H5 那边配合联调，确认编码规范两边一致。

4.3 登录态怎么处理比较稳

如果 H5 页面需要登录态，最直接的方案就是：小程序端先登录拿 token，把 token 通过 query 传给 H5，H5 再把 token 带到自己的接口请求里。

这个方案简单直接，但有一个安全注意点：token 会暴露在 URL 里。如果业务对安全性要求高，不建议直接把一个长期有效的 token 明文传过去，可以换成一个短时效的 ticket，H5 端拿 ticket 去后端换取正式登录凭证，这样即使 URL 被截获，影响面也可控。

另一种思路是往 storage 里写数据，H5 页面里通过uni.getStorageSync去读。但这里有个大坑：小程序端写入的 storage，H5 页面在小程序 webview 里运行时并不一定能直接读取。H5 要访问小程序侧的 storage，需要依赖 uni-app 的 H5 SDK 作为桥接，不是所有项目都接了这个 SDK。所以更通用的方案还是通过 URL 显式传参，后端的鉴权认证默认都能收到。

还要提一下 cookie 依赖的问题。如果 H5 的接口强依赖 cookie 会话，而 H5 域名和小程序业务域名不是同一个，在 webview 内会存在 cookie 跨域问题，处理起来非常麻烦。我的建议是优先推动后端把鉴权方式改成 token 或自定义 header，从根上绕开 cookie 这个坑。

5. 小程序和 H5 之间的双向通信

5.1 H5 往小程序发消息：postMessage 的正确用法

很多场景下，H5 页面内部产生了交互变化后，需要把结果通知给小程序端。比如用户填完了一个表单、观看完了某个视频、在 H5 里点了“申请通过”按钮，这些状态小程序原生层往往也需要感知。微信官方给的通道是wx.miniProgram.postMessage。

要在 H5 里调用这个方法，需要先在 H5 页面中引入微信官方 JSSDK：

<script src="https://res.wx.qq.com/open/js/jweixin-1.3.2.js"></script>

然后在使用到的地方调用：

wx.miniProgram.postMessage({ data: { action: 'complete', orderId: '123456' } })

小程序端通过 webview 组件的message事件来接收：

<web-view :src="webUrl" @message="handleMessage"></web-view>

handleMessage(event) { const data = event.detail.data console.log('收到 H5 消息', data) }

这里必须重点提醒一个特别容易踩的坑：postMessage发出来的消息，并不是立即触发小程序的message事件。微信官方的规则是，需要在小程序页面被销毁、用户点击右上角分享、或者点击返回按钮离开页面时，消息才会集中发送给小程序端。

也就是说，你在 H5 里点了某个按钮并调用了postMessage，小程序端不会立刻收到回调，而是等用户返回上一页时才收到。这个机制让很多想做实时交互的需求变得很别扭。比如你希望 H5 里点一个按钮，小程序端立刻更新某个状态，只靠postMessage是实现不了的。真要做实时通知，得往下看。

5.2 小程序往 H5 发消息：改 src

小程序端主动往 H5 塞数据，官方没有和postMessage对等的通道。最朴素也最可靠的方式，就是修改src，把要传的数据作为 query 参数加到 URL 上，然后重新赋值给 webview 的src。

这样做的好处是 H5 一定能收到，因为网页整个重新加载了；坏处也很明显，页面会刷新，用户的浏览状态会丢失，体验流畅度受影响。

在实际项目中，我见过有同事用“小程序端定时器不断修改 URL 后面时间戳参数”的方式去模拟实时通信，让 H5 反复 reload 拉最新数据。这个做法我非常不建议，既浪费用户流量又影响体验，而且频繁加载还可能被 H5 服务端当成异常请求拦截。

5.3 用页面跳转来做事件通知

如果你的场景是“H5 里发生了某个操作，需要跳回小程序原生页面”，其实可以不依赖消息事件，直接在 H5 里调用wx.miniProgram.navigateTo，传一个小程序的页面路径即可。

wx.miniProgram.navigateTo({ url: '/pages/order/detail?id=123' })

同理，H5 里也可以调用wx.miniProgram.navigateBack返回上一页，或者调用wx.miniProgram.reLaunch重开页面。这几个 API 只要 JSSDK 加载成功，在 webview 的 H5 里都能正常使用。

这种方式配合postMessage，基本能覆盖绝大多数业务需求。如果你的需求不是像在线聊天、实时协作这种强交互场景，webview 完全够用。如果真要做实时通信，那就得考虑在 H5 里自己接 WebSocket、轮询接口，再通过 postMessage 把结果同步回小程序端，但这是另一套复杂方案了，不是 webview 本身能解决的。

6. 常见问题与排查思路实录

6.1 webview 白屏，页面加载不出来

白屏最常见的原因就是域名没有配置到业务域名白名单，尤其是线上环境。报错会直接提示“不支持打开非业务域名”。排查路径很简单：先在开发者工具里看有没有报错，再去看微信公众平台后台的业务域名列表里是否包含当前域名，最后再确认校验文件是否还能正常访问。

还有一种情况是页面偶尔白屏，刷新一下又能打开。这种大概率是 H5 服务端响应慢或者超时导致。建议在 H5 端加一个加载超时提示，或者在小程序 webview 外层加一个 loading 占位，避免用户以为小程序卡死了。

6.2 网页能打开，但只能看到一部分内容

这个大概率是样式问题。在部分基础库版本中，webview 的高度默认是 100%，但如果外层 view 设置了 padding 或 margin，就会把可视区域挤掉一部分。检查一下外层 template，确保没有额外的样式干扰。需要强制占满时，可以直接写：

web-view { width: 100%; height: 100%; }

另外，如果你的页面启用了自定义导航栏，webview 区域会从导航栏下方开始，不占满全屏。这个属于正常现象，不算 bug。但如果你期望的是沉浸式全屏，需要调整页面的导航栏配置。

6.3 页面标题不对，导航栏显示的还是小程序标题

webview 加载的网页标题，微信小程序并不会自动同步到小程序导航栏。如果你希望导航栏标题跟随网页变化，有两个方案：一是在 H5 里调用wx.miniProgram.postMessage把 title 传回来，小程序端在message事件里动态修改导航栏标题；二是在小程序页面配置里写死一个标题。网页内容变化频繁，就用方案一，否则直接写死省事。

6.4 webview 压住了自定义组件

webview 是原生组件，层级天然在普通组件上方，这是老生常谈的坑了。如果你在小程序页面里用普通 view 放了一个悬浮按钮，真机上大概率会被 webview 盖住。处理方式有两个：一是把悬浮元素改成cover-view，这是微信专门为覆盖原生组件准备的；二是把按钮放到 H5 页面内部去渲染，由 H5 自己处理交互，不依赖小程序端覆盖层。

6.5 提示“页面无法打开”或协议错误

如果报错信息里有“无法打开”或“协议错误”，先确认 URL 协议是不是https://。另外检查 URL 里有没有空格，空格在某些环境下会被当成非法字符。还有一个不太常见但确实遇到的坑：URL 里带了中文字符没有做编码，导致真机上加载失败。这种情况用encodeURI对整个地址包一层就能解决。

6.6 问题速查表

写到这，uni-app 微信小程序通过 webview 跳转到其他网址的完整链路基本过了一遍。说实话，webview 真不是“贴一个标签”那么简单，它背后牵扯到微信小程序的安全校验体系、原生组件渲染机制和前后端通信协议三个层面的东西。我第一次上线这类功能时，就是在测试环境跑得好好的，一提交体验版就被用户反馈页面打不开，后来查了一整个下午才发现是业务域名没配置。所以我把这套排查路径和避坑记录整理出来，希望你下次做的时候能够一次跑通。真要遇到奇怪的问题，别慌，对照上面的排查表格一步步看，大多数问题都逃不开那几类原因。