企业官网建设流程全解析

去年接了个公众号活动页的项目，需求本身不复杂：一个报名 H5，用户在微信里打开、填表单、提交、支付，还能通过微信分享拉朋友来报名。结果第一版上线当天就被运营找上门——分享出去的卡片没有标题没有缩略图，一串裸链接躺在聊天记录里；同一套代码在 iPhone 上完全正常，在几台 Android 机器上直接白屏。这种问题，在微信网页开发里几乎每天都在发生。

微信网页开发，说白了就是跑在微信内置浏览器里的网页开发，但它和普通移动端 H5 最大的区别在于：你面对的不只是一个移动浏览器，还有微信这一整套账号体系、接口权限、平台约束。这篇文章不打算复读官方文档，而是把一套完整、能跑起来的链路拆开讲清楚——从账号资质和域名配置开始，到网页授权、JS-SDK 签名、JSAPI 支付，再到我这些年实际踩过的坑和排查思路。不管你是刚入门前端的同学，还是写过多年 H5 但一直没系统对接过微信接口的老手，都可以照着这篇文章把整个逻辑串起来。

1. 微信网页开发到底在开发什么：先分清三类能力和一个边界

微信给网页开发者开放的能力，归纳起来是三类：网页授权、JS-SDK、JSAPI 支付。先把这三类的职责边界理清楚，后面写代码才不会乱。

第一类是网页授权，也就是 OAuth2.0。用户在微信里打开你的页面，微信可以把这个用户的 openid 通过回调传给你，必要时还能给你昵称、头像这些基础资料。这相当于微信帮你做了"登录"这件事，你不需要再引导用户输手机号验证码。第二类是 JS-SDK，它让网页具备调用微信原生能力的手段：自定义分享卡片、扫一扫、获取地理位置、选择相册图片、调起录音等等。第三类是 JSAPI 支付，也就是在公众号网页里直接发起微信支付的整套接口，一般配合网页授权使用，先拿到 openid，再下单调起支付。

除了这三类能力，还有一个很容易被忽略的"隐藏约束"：微信内置浏览器的兼容性问题。iOS 端跑的是苹果自家的 WebView 内核，Android 端则是各家手机厂商的 WebView 版本五花八门，同一个 ES6 箭头函数在一台老机器上可能直接报语法错误。这不是接口问题，是纯前端工程问题，但它恰恰是很多项目上线后翻车的高发区。

1.1 它和小程序到底差在哪

经常有人纠结：同样的功能，做成小程序还是做成微信网页 H5？我的判断标准很简单——长期服务型产品选小程序，短期时效型活动选 H5。

小程序有自己的一套运行时和组件体系，登录、分享、支付都是平台级能力，官方封装得好，开发体验统一，但它要过审核、受平台规范约束，发布一个版本要等审核。H5 页面部署在自己服务器上，改个文案、调个样式，前端发版立刻生效，迭代路径非常短，非常适合做活动页、运营落地页、问卷表单这类强时效、需要频繁改动的内容。代价就是开头说的那三类能力都要自己接，兼容性要自己扛，而且微信侧对域名、HTTPS、备案这些东西卡得很严。

1.2 典型场景对照

用一个表格把这几年我见到的微信网页开发场景归纳一下，方便你判断自己在做的属于哪一类、需要哪些能力：

看表就知道，网页授权几乎是所有场景的地基；分享卡片是活动类页面的标配；支付则是电商和报名类业务的关键一环。后面的章节就按这个依赖顺序展开。

2. 动手前的配置清单：公众号后台和服务器缺一不可

写代码之前，先花一个下午把资质和环境准备好。这一块出问题，后面所有接口调用都会以各种奇怪的报错形式失败，而且你很难从代码层面定位，因为错误往往不是语法问题，是权限问题。以下配置流程是基于我平时项目最常见的做法整理出来的，具体字段名称以公众号后台当前版本为准。

2.1 先确认你的公众号类型

做微信网页开发，首先得有一类"能干活"的公众号。微信公众平台里公众号分订阅号和服务号，两者能力差异非常大。简单说：

• 服务号：可以申请微信认证，认证后能使用网页授权（尤其是能拿用户资料的 snsapi_userinfo 那种）、JS-SDK 完整能力、JSAPI 支付。做微信网页开发，认证服务号是标准配置。
• 订阅号：偏内容发布，接口权限少很多，基本没有支付能力，网页授权也只能做最低限度的静默授权。如果你只有一个订阅号，建议趁早跟业务方升级成服务号，或者另外申请一个认证服务号来承载 H5 页面。

这里插一句我常跟团队说的话：开发前一定要把账号权限截图确认一遍，别等接口调用报错了再回头补认证，认证周期要一两周，很耽误事。

2.2 后台三个域名配置

登录公众号后台，在"设置与开发-公众号设置-功能设置"里，有三个和 H5 相关的配置项：网页授权域名、JS接口安全域名、业务域名。三个域名配置都需要你将微信给定的一段校验文件放到对应域名的根目录或指定路径下，能通过 HTTP 访问到，微信才能确认这个域名是你的。

• 网页授权域名：用于 OAuth2.0 回调，配置后 redirect_uri 的主域名必须和它一致。
• JS接口安全域名：用于 JS-SDK，页面 URL 的域名必须在这个列表里，否则 wx.config 签名校验会失败。
• 业务域名：用于消除微信内打开网页时的"非官方网页"风险提示。配置后，微信内置浏览器打开的页面域名必须匹配。

另外基本配置里还有一个容易被漏掉的"IP 白名单"：调用 cgi-bin 系列接口（比如获取全局 access_token）的服务器出口 IP 必须在白名单里，否则接口会返回 40164。如果你用云服务器，一定要把服务器的公网 IP 加进去，本地调试的 IP 也要临时加。

2.3 服务器与 HTTPS 环境

微信侧现在对 HTTPS 的要求几乎是硬性的。网页授权回调地址、分享链接、支付相关请求，官方都要求 HTTPS，iOS 端对非 HTTPS 页面也会各种限制。所以服务器上第一个动作就是挂证书，别拖。

第二个动作是准备一个全局缓存。微信的全局 access_token 有效期是 7200 秒，但官方接口有频率限制，频繁获取会被限流，所以必须把 access_token 和 jsapi_ticket 缓存起来，用 Redis 或者数据库都行，设置略小于 7200 秒的过期时间，比如 7100 秒。这个缓存的稳定性直接决定线上接口的稳定性，很多"接口时好时坏"的问题，本质都是 token 被并发刷新导致缓存击穿。

3. 网页授权 OAuth2.0：让 H5 页面认出微信里的用户

网页授权是微信网页开发的地基，因为没有它你就拿不到用户的 openid，支付、会员识别这些全做不了。这一节把流程讲透，代码给你能直接抄的版本。

3.1 两种 scope 的取舍

网页授权有两种 scope，决策成本很低，但很多人选错。snsapi_base 是静默授权：用户跳转时无感知，微信直接带 code 回到你的回调地址，你拿到的是 openid，仅此而已。snsapi_userinfo 是非静默授权：页面上会弹出一个微信官方的授权确认框，用户点"同意"后，你才能拿到 openid 之外的昵称、头像等基础资料。

我的建议是：能静默就静默。如果业务只是需要区分用户——比如判断这个人有没有报过名、有没有领过券，snsapi_base 就够了；只有页面必须展示用户头像昵称，或者需要把用户身份跟业务账号强制绑定，才用 snsapi_userinfo。每多一次授权弹窗，用户的流失率都会肉眼可见地上升，活动页尤其明显。

还要提醒一句：微信对用户资料字段是有策略性调整的，昵称头像这类资料在部分场景下会返回脱敏或占位内容。所以做业务时不要把头像昵称当作强依赖字段，把它当锦上添花就行。

3.2 从授权链接到回调的完整代码

网页授权的流程是标准的 OAuth2.0 授权码模式，三步：引导用户跳转微信授权页；微信回调你的 redirect_uri 并带上 code；你用 code 换 openid（以及可能的用户资料）。下面是 Node.js + Express 的最小实现：

const express = require('express'); const axios = require('axios'); const app = express(); const APPID = '你的AppID'; const SECRET = '你的AppSecret'; // 注意：redirect_uri 要提前 URL 编码 const REDIRECT_URI = encodeURIComponent('https://example.com/wechat/oauth/callback'); // 第一步：把用户引导到微信授权页 app.get('/wechat/login', (req, res) => { const authorizeUrl = 'https://open.weixin.qq.com/connect/oauth2/authorize' + '?appid=' + APPID + '&redirect_uri=' + REDIRECT_URI + '&response_type=code' + '&scope=snsapi_base' + // 按需求切换为 snsapi_userinfo '&state=' + (req.query.state || '') + '#wechat_redirect'; res.redirect(authorizeUrl); }); // 第二步：微信回调到这里，code 就在 query 里 app.get('/wechat/oauth/callback', async (req, res) => { const { code, state } = req.query; if (!code) return res.status(400).send('缺少 code'); const tokenRes = await axios.get( 'https://api.weixin.qq.com/sns/oauth2/access_token', { params: { appid: APPID, secret: SECRET, code: code, grant_type: 'authorization_code' } } ); const { access_token, openid, scope } = tokenRes.data; let userInfo = { openid }; if (scope && scope.includes('snsapi_userinfo')) { const infoRes = await axios.get( 'https://api.weixin.qq.com/sns/userinfo', { params: { access_token, openid, lang: 'zh_CN' } } ); userInfo = infoRes.data; } // 拿到 openid 和用户资料后，写入自己的登录态 // 比如写 session、签发 JWT，然后重定向回业务页面 res.redirect('/dashboard?openid=' + openid); });

代码不复杂，核心就两个 HTTP 请求。第一个用 code 换 token，第二个根据 scope 决定要不要拉用户资料。

3.3 三个容易翻车的细节

第一个：redirect_uri 必须和后台配置的网页授权域名保持主域名一致，而且授权链接里的 redirect_uri 一定要 URL 编码，直接拼一个带着 & 符号的裸地址进去，授权回调会被截断。

第二个：code 是一次性的，有效期大概五分钟，用过就作废。线上经常出现一种情况：用户授权成功后回退到上一步再前进，微信又用同一个 code 回调一次，后端重复兑换就报 invalid code。处理方式是在回调里对 code 做去重，或者兑换失败时静默重定向回授权入口。

第三个：openid 是用户在某个公众号下的唯一标识，换个公众号就不一样了。如果你们有多个公众号，或者有小程序，想统一识别同一个用户，得去微信开放平台把账号绑定到一起，用 unionid。业务设计上，建议从一开始就把 unionid 作为用户主键来规划。

4. JS-SDK 签名：分享、扫码、定位等能力的统一入口

拿到 openid 只是第一步，活动页真正出效果靠的是 JS-SDK，尤其是自定义分享。而 JS-SDK 所有接口都有一个统一的入场券——签名（wx.config 里的 signature）。这一节把签名的原理、实现和排错讲清楚，你基本就告别"分享卡片没图"这类低级问题了。

4.1 签名为什么这么麻烦

很多人第一次接触 JS-SDK 都懵：为什么我不能直接在前端写死一个 appId 然后调分享？微信要求每次调用前都要 wx.config，里面必须带一个当前页面 URL 实时算出来的签名，目的是证明"这个页面确实来自你配置过的安全域名"。所以签名是绑定了三样东西的：公众号、页面 URL、当前时间（还有随机串），三者任何一个对不上，签名就失效。

签名的生成链路是这样的：先用 AppID 和 AppSecret 换取全局 access_token，再用它换取 jsapi_ticket，最后用 jsapi_ticket 加 noncestr、timestamp、url 拼一个字符串做 SHA1 哈希。这里的 access_token 和网页授权那节的 access_token 是两回事，一个是"公众号级别"的全局凭证，一个是"用户级别"的临时凭证，千万别搞混——我见过有人把前端拿到的用户 token 直接拿去换 ticket，折腾了一整天。

4.2 后端签名实现

下面这段 Node.js 代码是实现签名的最小骨架，token 和 ticket 缓存、签名生成都包含了：

const crypto = require('crypto'); // 1. 获取全局 access_token（务必缓存，这里用 redis 示例） async function getAccessToken() { const cached = await redis.get('wechat_global_access_token'); if (cached) return cached; const url = 'https://api.weixin.qq.com/cgi-bin/token' + '?grant_type=client_credential&appid=' + APPID + '&secret=' + SECRET; const res = await axios.get(url); // 正常返回：{ access_token, expires_in } if (res.data.access_token) { await redis.set( 'wechat_global_access_token', res.data.access_token, 'EX', 7100 // 小于官方 7200 秒，留出余量 ); } return res.data.access_token; } // 2. 获取 jsapi_ticket（同样缓存） async function getJsapiTicket() { const cached = await redis.get('wechat_jsapi_ticket'); if (cached) return cached; const accessToken = await getAccessToken(); const res = await axios.get( 'https://api.weixin.qq.com/cgi-bin/ticket/getticket', { params: { access_token: accessToken, type: 'jsapi' } } ); if (res.data.ticket) { await redis.set('wechat_jsapi_ticket', res.data.ticket, 'EX', 7100); } return res.data.ticket; } // 3. 生成签名 async function buildSignature(pageUrl) { const jsapiTicket = await getJsapiTicket(); const nonceStr = Math.random().toString(36).slice(2, 18); const timestamp = Math.floor(Date.now() / 1000); // 微信要求：url 是当前页面的完整地址，去掉 # 及其后的部分 const cleanUrl = pageUrl.split('#')[0]; const string1 = [ 'jsapi_ticket=' + jsapiTicket, 'noncestr=' + nonceStr, 'timestamp=' + timestamp, 'url=' + cleanUrl ].join('&'); const signature = crypto.createHash('sha1').update(string1).digest('hex'); return { appId: APPID, timestamp, nonceStr, signature }; }

这里有个很关键的变量：pageUrl。微信要求签名用的 url 必须和页面在微信里实际加载的完整 URL 一致（去掉 hash 后的部分），包括 query 参数。所以正确做法是前端把自己的 location.href.split('#')[0] 传给后端，后端拿这个值去签名，绝不要在后端写死一个"默认首页地址"。

4.3 前端 wx.config 与分享卡片配置

后端返回签名参数后，前端要做的是加载微信 JS-SDK 脚本，然后调用 wx.config。核心代码如下：

wx.config({ debug: false, // 调试期可以开 true，看完记得关 appId: signRes.appId, timestamp: signRes.timestamp, nonceStr: signRes.nonceStr, signature: signRes.signature, jsApiList: [ 'updateAppMessageShareData', 'updateTimelineShareData', 'scanQRCode', 'getLocation' ] }); wx.ready(() => { const shareInfo = { title: '活动标题，别太长', desc: '一句话描述，吸引点击', link: 'https://example.com/activity?from=share', imgUrl: 'https://example.com/share-cover.png' // 建议 300x300 以上公网可访问 }; wx.updateAppMessageShareData(shareInfo); wx.updateTimelineShareData(shareInfo); }); wx.error((res) => { // 这里会拿到类似 invalid signature 的报错 console.error('wx.config 失败', res.errMsg); });

分享接口有旧版和新版两组，旧版的 wx.onMenuShareTimeline、wx.onMenuShareAppMessage 在官方文档里已标记废弃，新项目直接用 wx.updateTimelineShareData 和 wx.updateAppMessageShareData 这组。注意分享图片必须是公网可访问的图，微信会自己去抓图，内网地址、本地路径、未备案域名下的图片都会导致缩略图不显示。

4.4 签名失效排查清单

签名失效是微信网页开发里最经典的坑，我把排查顺序列一下，照着走基本十分钟内定位：

• 先看页面实际 URL 是什么，再看传给后端签名接口的 URL 是什么，两者必须完全一致（去掉 hash）。最常见的坑：页面带着 ?from=xxx 访问，后端写死了不带 query 的地址。
• 打开 wx.error 的日志，如果提示 invalid signature，优先检查 JS 接口安全域名是否包含当前域名，以及校验文件是否还能正常访问。
• 检查 jsapi_ticket 缓存：是不是多个环境共用了同一个 Redis，A 公众号的 ticket 被 B 公众号拿来签名。
• 检查服务器时间：签名里的 timestamp 来自服务器，如果服务器时间跟真实时间差得多，也会被判定无效。
• 检查签名是否是小写 SHA1 值，有些语言库默认输出大写 Hex，微信不认。

5. JSAPI 支付：在网页里收钱的三段式流程

如果业务涉及收费，微信网页开发里对应的就是 JSAPI 支付（公众号支付）。这一节讲它完整跑通的必要条件和三段式流程。

5.1 先满足支付的门槛

JSAPI 支付的前提很硬：认证服务号 + 已开通的微信支付商户号 + 服务号和商户号完成绑定。另外前端页面必须通过网页授权拿到用户 openid，因为 JSAPI 支付是按"某一用户在某个商户下单"来设计的，没有 openid 就调不起支付。

这里顺带把支付形态说清楚：微信内网页用的是 JSAPI 支付；如果是外部浏览器（比如手机系统浏览器）打开网页，用的是 H5 支付。两者的下单接口和前端调起方式都不一样，别混着用。本文只讲公众号内的 JSAPI 支付。

5.2 统一下单与调起支付的代码骨架

流程分三步：后端统一下单拿 prepay_id；后端生成支付签名返回前端；前端调起支付键盘并处理回调。很绕的是第二步其实还有一次签名，因为微信支付商户平台的参数签名和 JS-SDK 的签名是两套体系。

后端统一下单（这里以 API v3 为例，老项目还在用 v2 的 XML 接口，字段大同小异）：

// 请求微信支付统一下单（API v3） // 请求头需要商户号、证书序列号、RSA-SHA256 签名 // 具体签名算法参考官方文档，这里省略 HTTP 层封装 const orderBody = { appid: APPID, mchid: MCHID, description: '活动报名费', out_trade_no: '20240101001', // 商户订单号，自己生成，要唯一 notify_url: 'https://example.com/pay/notify', amount: { total: 1000, // 单位是分！1000 分 = 10 元 currency: 'CNY' }, payer: { openid: openid // 来自网页授权 } }; // POST https://api.mch.weixin.qq.com/v3/pay/transactions/jsapi // 返回中的 prepay_id 用于生成前端调起支付的参数

拿到 prepay_id 后，后端用 prepay_id、时间戳、随机串、AppID 再次签名，把下面这几个参数返回给前端：

// 前端拿到支付参数后调起支付 wx.chooseWXPay({ timestamp: payParams.timeStamp, // 秒级时间戳，String nonceStr: payParams.nonceStr, package: payParams.package, // 形如 prepay_id=xxxxx signType: payParams.signType, // v3 用 RSA，v2 用 MD5 或 HMAC-SHA256 paySign: payParams.paySign, success: (res) => { // 只能做 UI 提示"支付中" // 真正的成功以服务端异步通知为准 }, fail: (err) => { // 用户取消支付或调起失败 } });

注意金额单位是分，这个是微信网页开发里出现率最高的低级错误：把元当分传，用户下单 10 元实际被扣 0.1 元。

5.3 异步通知：钱到账的唯一依据

调起支付后，微信会把支付结果通过异步通知 POST 到你在下单时填的 notify_url。前端 success 回调只能当作"用户完成了支付动作"的提示，绝不能当作"订单已支付"的依据，因为用户可能支付成功但网络断开，前端收不到回调。

服务端收到异步通知后要做四件事：验签解密（v2 是 MD5/HMAC 验签，v3 是平台证书验签加数据解密）、查订单确认 out_trade_no 对应订单、核对金额是否和订单一致（防止伪造回调）、更新订单状态并做幂等处理（同一通知可能发多次）。最后按文档要求返回成功应答，否则微信会按策略重试。

做得不够严谨的话，还需要一个兜底：用微信支付查单接口主动查订单状态。异步通知可能延迟、可能丢失，成熟项目里都是"回调 + 定时查单"双保险。

6. 我在实践中踩过的坑：从签名到缓存的完整排查链路

前面把正确流程讲完了，这一节专门讲踩坑，包括一次真实的分享失败排查过程和两个高频问题的定位思路。排查经验这种事，光看结论没用，重要的是复现一遍思考链路。

6.1 一次分享卡片异常的完整排查过程

还是开头那个活动页。现象是：分享到聊天里的卡片没有标题、没有缩略图，iOS 和 Android 都出现，但并不是每次都不行，偶尔正常。

我当时的第一反应是前端分享参数配置有问题，于是打开页面控制台检查，发现 wx.config 竟然报 invalid signature。奇怪的是签名接口在服务器日志里正常返回了参数，问题到底在哪？

接着我把前后端的 URL 对了一下：前端传给后端签名接口的值是https://example.com/activity/page-a?channel=share，而后端代码里对 pageUrl 做了一个处理——从 Redis 里取了一份"页面地址白名单"，匹配不到就用默认值https://example.com/activity/page-a。也就是说，带 query 参数访问时，签名用的 URL 和页面实际 URL 不一致，微信校验自然就挂了。之前偶尔正常，是因为有几次访问恰好不带参数。

修复方式很简单：后端签名接口直接信任前端传来的 location.href.split('#')[0]，去掉白名单逻辑，只在必要时做域名校验。改完再测，invalid signature 消失，分享卡片恢复。这件事给我的教训是：签名接口的入参应该就是"当前页面真实 URL"，任何二次加工都会引入不确定性，微信的签名机制在你试图自作聪明的时候一定会惩罚你。

6.2 iOS 和 Android 的 WebView 差异

分享问题解决了，白屏问题还在。排查后发现是 Android 一台旧机器不支持项目里使用的可选链语法，转译配置只针对 iOS 做了适配。微信内 Android WebView 版本碎片化严重，这是做微信网页开发绕不开的现实。

处理兼容性的通用打法就一条：给自己的静态资源做语法转译和降级，别默认用户手里是最新手机。另外，HTML 里的视口设置、安全区适配、字体栈这些基础配置最好做成一套模板，每个项目直接复用，省得每次从零踩一遍。

6.3 调试三板斧和常见错误码

微信网页开发的调试比普通 H5 麻烦，因为没有传统浏览器那种可自由审查的环境。我的三板斧是：

• 前端调试：在页面里临时引入 vConsole，打开后能看到 console 日志、网络请求和 cookie，JS-SDK 报错、接口返回都能直接看到。调试完记得从代码里移除或按环境开关。
• 后端日志：所有调用微信接口的响应都完整打印，尤其是 errcode 和 errmsg。很多问题其实后端日志里一眼就能看出来，比如 access_token 过期、IP 不在白名单。
• 官方工具：微信开发者工具可以建"公众号网页"类型的项目，配合前端代码做初步调试；但真机上的 WebView 行为和工具模拟器仍有差异，最终必须真机验证。

后端接口报错时，记住这几个常见错误码能省很多时间：

7. 几个让我少走弯路的实践习惯

内容到这里，核心链路都讲完了。最后分享几个我做了多年微信网页开发后形成的习惯，都是拿时间换来的。

第一个习惯是抽一个独立的微信能力服务。把 access_token、jsapi_ticket 的缓存、签名生成、OAuth 回调、支付下单这些逻辑收敛到一个服务里，其他业务项目只调 HTTP 接口。这样 token 缓存只维护一份，多个项目不会互相踩踏，签名逻辑也只修一处。

第二个习惯是前端统一封装 wx 初始化。把 wx.config 封装成一个返回 Promise 的函数，页面任何地方要调分享、扫码，先等待初始化完成再调接口，避免多个接口并发初始化导致 wx.ready 没触发。

第三个习惯是做降级。任何微信接口都会失败：非微信浏览器打开、接口权限配置漏了、用户微信版本太老，全都有可能。页面里分享按钮和支付入口要做降级处理，外部浏览器打开时要么提示"请在微信中打开"，要么走一套非微信替代流程，别让用户卡在一个无响应按钮上。

第四个习惯是上线前用清单扫一遍。域名配置、校验文件、IP 白名单、HTTPS 证书、签名接口、分享图片、支付回调地址，每一项都过一遍。很多时候线上出问题不是代码逻辑，是某个人忘记在后台把新域名加进 JS 接口安全域名。

第五个小技巧，也是我最近才总结出来的：给分享链接和页面 URL 带上来源参数，比如 ?from=xxx，这样既能做渠道统计，也能在签名时靠它验证"页面 URL 究竟是哪来的"。签名接口收到前端 URL 后，先校验域名属于自己，再原样参与签名，既安全又不容易出偏差。

做微信网页开发这几年，我的最大体会是：这个领域没有太多高深算法，真正的难点全在细节——域名对不对、缓存过期没有、URL 是否一致、回调有没有验签。把这些细节养成习惯，项目就能少很多半夜被拉起来排查的体验。