1. 先搞清楚 previewFile 到底解决什么问题边界又在哪企业微信内嵌 H5 这个场景做过的人都知道它跟普通浏览器里跑页面完全是两套逻辑。你本地浏览器打开一切正常扔进企业微信客户端里文件点不动、预览白屏、下载无声无息这类问题几乎每个做企微自建应用的前端都遇到过。微信 JS-SDK 里那个wx.previewFile就是官方给内嵌 H5 提供的一套文件预览与下载入口专门用来在企微客户端内部打开 PDF、Word、Excel、PPT、图片这类文档而不是把用户甩到系统浏览器里再干瞪眼。这篇东西主要面向的是用vue2.0技术栈、把页面挂到企业微信里、需要做JS-SDK 鉴权并调用wx.previewFile的前端和全栈同学。我会把后台配置、签名算法、前端封装、踩坑排查整条链路都讲透代码可以直接抄。适合有一定前端基础、但第一次在企业微信里接 JS-SDK 的人也适合接过一次但老是报invalid signature想彻底搞明白原理的人。我先把结论摆在前面wx.previewFile本身调用很简单真正难的是它前面的鉴权链路和它背后的环境差异。90% 的“调不起来”问题都不在 previewFile 这一行而在wx.config有没有成功、签名算得对不对、URL 取得对不对、以及文件链接能不能被企微客户端下载到。所以别一上来就盯着 previewFile 的 API 文档看先把鉴权这条水管打通。1.1 内嵌 H5 处理文件的老办法为什么不灵在没有接 JS-SDK 之前大部分人的第一反应是用a hrefxxx.pdf download或者window.open(url)再或者window.location.href url。这三种写法在普通浏览器里都能凑合但在企业微信内嵌 WebView 里表现非常不稳定。a标签的download属性在很多内嵌 WebView 里被忽略点下去要么没反应要么直接在当前 WebView 里打开一个纯文本流把整个页面顶掉用户回都回不来。window.open更麻烦企业微信客户端会拦截弹窗有时候静默失败有时候打开一个空白页。用window.location.href跳文件流如果后端返回的是Content-Disposition: attachmentWebView 未必认可能直接渲染成一串乱码。这些方案的通病是你没法控制“预览”还是“下载”也拿不到打开成功或失败的回调用户体验完全靠猜。而wx.previewFile走的是企业微信客户端原生能力它在客户端内部用一个独立的文件预览页打开文档界面是原生的有分享、有下载、有关闭页面上下文不会被破坏用户返回后还停留在原来的 H5。这就是为什么只要目标是企微就值得专门接这一套。1.2 wx.previewFile 的定位与能力边界wx.previewFile的参数其实就几个核心是这四个url文件地址必填、name文件名带扩展名用于展示、size文件大小字节数用于显示进度、type文件类型比如 pdf、doc、xls部分版本才支持。官方文档写得很简洁但真实使用里约束不少先记在脑子里它依赖 JS-SDK 鉴权wx.config没成功后面全白搭。它只在企业微信客户端内有效普通浏览器、微信里非企微都不认。下载的url必须是客户端能直接访问的地址如果后端接口需要携带 Cookie 或自定义请求头才返回文件企微客户端拉不到。文件格式受客户端支持范围限制冷门格式可能只能下载不能预览。size虽然可选但不传的话进度条可能显示不准传了体验明显更好。知道边界之后很多“玄学问题”就有解释了白屏多半是文件 URL 拉不到没反应多半是 config 没成功一直转圈多半是文件太大而size没给对。1.3 为什么 vue2.0 项目要多做一层封装在 vue2.0 里我强烈建议不要把wx.config和wx.previewFile散落在各个页面组件里。原因很实在企微的 config 是有状态的同一个页面里重复 config 可能互相覆盖而签名接口涉及后端请求如果每个组件都去算一次签名接口调用量会爆炸缓存也没法统一管理。正确的姿势是在main.js或一个独立的utils/wx-sdk.js里做全局单例封装负责拿签名、调wx.config、暴露一个 Promise 化的ready钩子业务组件只管await这个 ready 之后再调previewFile。这样一来签名只算一次config 只调一次哪个页面要预览文件直接引封装好的方法就行。这个思路在后面第 3 章我会用完整代码展开。2. 企业微信后台与企业侧的前置配置一步都不能少很多人以为接 JS-SDK 是纯前端的事配好域名就行其实企业微信这一侧的前置配置才是第一步配错一个字段后面签名怎么算都过不去。这一章把后台配置和签名原理讲清楚理解了签名到底签的是什么你排查问题就有了方向而不是靠反复重启服务碰运气。2.1 可信域名、应用与可见范围在企业微信管理后台你要走的是“应用管理 → 自建 → 你创建的应用”这条路径。这里有几个关键字段必须配对可信域名的校验企微要求你下载校验文件放到域名根目录能通过http(s)://你的域名/文件名直接访问到才算验证成功。注意是企业微信客户端能访问到的公网地址localhost和纯内网 IP 都不行。应用主页 / 网页授权及 JS-SDK 域名这是 JS-SDK 能生效的前提必须和前端页面实际所在的域名完全一致包括协议和端口。带www和不带www是两个域名http和https也是两个域名。可见范围决定哪些成员能打开这个应用。测试阶段把所有相关同事都加进去别出现“你能进我不能进”的情况。这里有个特别容易被忽略的点如果你用的是带二级路径的部署比如页面挂在https://a.example.com/h5/下可信域名填的是https://a.example.com这没问题但如果你填成了带路径的https://a.example.com/h5很多情况下会校验失败。域名就填到域名路径交给页面自己。注意可信域名一旦改动往往需要重新走校验流程配置期间最好把域名固定下来别在开发中途换域名否则签名和 config 全要重来。2.2 JS-SDK 鉴权签名到底签了什么企业微信的 JS-SDK 鉴权本质上是把你当前页面的 URL 和一堆随机参数、票据一起做哈希生成一个签名客户端拿到后自己再算一遍对得上才允许你调 API。整条链路是这样的用corpid和corpsecret换取access_token。用access_token换取jsapi_ticket。用jsapi_ticket、noncestr、timestamp、url四个字段拼成字符串做sha1得到signature。前端拿到appId、timestamp、nonceStr、signature去调wx.config。注意拼串的顺序是有严格规定的一定是jsapi_ticketxxxnoncestrxxxtimestampxxxurlxxx字段名大小写、、一个都不能错顺序也不能颠倒。我第一次接的时候就是因为把noncestr写成了nonceStr排查了小半天。再强调一个致命细节参与签名的 url 是当前页面的完整 URL但要去掉#及其后面的部分。因为#后面是前端路由的 hash客户端根本不知道它拿到的是不带 hash 的地址。如果你的页面里带了查询参数?a1b2这些参数要保留。更稳的做法是前端主动把自己当前的 URLlocation.href.split(#)[0]传给后端后端用它算签名而不是后端自己猜。还有一个 iOS 和安卓的差异坑iOS 上 WebView 的 URL 在页面内路由切换后可能不刷新导致拿到的 URL 和签名时用的 URL 对不上。稳妥方案是每次进入需要调 JS-SDK 的页面都用当前实时 URL 重新走一次 config或者干脆把需要预览的页面做成独立 URL减少 SPA 内部路由切换带来的干扰。3. Vue2.0 工程里的完整落地实现理论和配置讲完这一章直接上代码把从引入 SDK 到封装预览方法跑通。我会按“引入 → 封装 config → 暴露预览方法 → 后端签名接口”的顺序来每一步都附上我实际项目里用的写法。3.1 JS-SDK 的引入方式与全局 config 封装企业微信的 JS-SDK 我一般直接在index.html里用 script 标签引入版本用官方推荐的 1.2.0 及以上script srchttps://res.wx.qq.com/open/js/jweixin-1.2.0.js/script为什么不 npm 装因为jweixin本质是个挂载全局wx对象的脚本企微要求它在页面初始化时加载走 script 标签最直接也避免打包工具把它 tree-shaking 掉。引进来之后window.wx就能用了。下面是我项目里的src/utils/wx-sdk.js做了单例封装import axios from axios let configPromise null function getSignature(url) { // 后端接口返回 appId、timestamp、nonceStr、signature return axios.get(/api/wx/jsapi-signature, { params: { url } }).then(res res.data) } export function initWxConfig() { if (configPromise) return configPromise const url window.location.href.split(#)[0] configPromise getSignature(url).then(data { return new Promise((resolve, reject) { window.wx.config({ beta: true, // 企业微信里调用部分能力需要开 debug: false, // 上线记得关掉 appId: data.appId, timestamp: data.timestamp, nonceStr: data.nonceStr, signature: data.signature, jsApiList: [previewFile, openDocument, getLocation, chooseImage] }) window.wx.ready(() { resolve(window.wx) }) window.wx.error(err { // 这里不要 reject 掉全局 Promise否则后续页面永远拿不到 configPromise null reject(err) }) }) }) return configPromise }这里有三个我特意处理的地方都是踩过坑总结出来的。第一configPromise做了缓存同一页面生命周期内只算一次签名避免重复请求。第二wx.error里把缓存的 Promise 清空这样失败后下次还能重试不然一次失败整个应用都废了。第三jsApiList里我把可能用到的接口都列上了但你也可以按需精简只列previewFile。3.2 预览组件的封装与调用姿势有了 config 封装业务侧调用就非常清爽了。我把它再包一层做了一个previewFile方法处理参数默认值和错误兜底import { initWxConfig } from /utils/wx-sdk export async function previewFile({ url, name, size, type }) { if (!url) throw new Error(文件地址不能为空) // 非企业微信环境直接降级 const ua navigator.userAgent.toLowerCase() if (!ua.includes(wxwork)) { window.open(url) return } const wx await initWxConfig() wx.previewFile({ url, name: name || 文件, size: size || 0, type: type || }) }组件里用起来就像普通 async 方法import { previewFile } from /utils/preview export default { methods: { async handlePreview(file) { try { await previewFile({ url: file.downloadUrl, name: file.fileName, size: file.fileSize }) } catch (e) { this.$toast(文件打开失败请稍后重试) console.error(previewFile error:, e) } } } }要点在于size尽量传真实字节数后端存文件时把文件大小一起返回别传字符串形式的 “2MB”企微要的是数字传错会导致进度条异常的。name一定要带正确的扩展名比如合同.pdf客户端靠扩展名决定用哪种预览器不带扩展名可能只给你下载。3.3 后端签名接口的实现细节签名必须在后端做原因很简单corpsecret和jsapi_ticket属于敏感凭据暴露到前端等于把整个企业的通讯录和消息能力送人。我一般用 Node.js 写一个中转接口逻辑分三步缓存access_token、缓存jsapi_ticket、计算签名。const crypto require(crypto) const axios require(axios) let tokenCache { value: , expireAt: 0 } let ticketCache { value: , expireAt: 0 } async function getAccessToken(corpid, secret) { if (tokenCache.value Date.now() tokenCache.expireAt) { return tokenCache.value } const res await axios.get(https://qyapi.weixin.qq.com/cgi-bin/gettoken, { params: { corpid, corpsecret: secret } }) tokenCache { value: res.data.access_token, expireAt: Date.now() (res.data.expires_in - 300) * 1000 } return tokenCache.value } async function getJsapiTicket(token) { if (ticketCache.value Date.now() ticketCache.expireAt) { return ticketCache.value } const res await axios.get(https://qyapi.weixin.qq.com/cgi-bin/get_jsapi_ticket, { params: { access_token: token } }) ticketCache { value: res.data.ticket, expireAt: Date.now() (res.data.expires_in - 300) * 1000 } return ticketCache.value } function buildSignature(ticket, noncestr, timestamp, url) { const raw jsapi_ticket${ticket}noncestr${noncestr}timestamp${timestamp}url${url} return crypto.createHash(sha1).update(raw).digest(hex) }两个缓存都留了 300 秒的安全余量因为access_token和ticket有效期都是 7200 秒而且同一个企业全局只有一份有效 token你在多处并发获取会互相踢掉。这也是为什么签名接口必须走服务端统一缓存不能每个请求都去拉一次。返回值组装好给前端module.exports async function handler(req, res) { const { url } req.query const token await getAccessToken(process.env.CORP_ID, process.env.CORP_SECRET) const ticket await getJsapiTicket(token) const noncestr Math.random().toString(36).slice(2, 16) const timestamp Math.floor(Date.now() / 1000) const signature buildSignature(ticket, noncestr, timestamp, url) res.json({ appId: process.env.CORP_ID, timestamp, nonceStr: noncestr, signature }) }注意url是从前端传进来的后端绝对不能用自己的域名去拼因为实际访问页面的域名可能经过代理后端和前端看到的域名不一定一致。以客户端传上来的 URL 为准这是最稳的。4. 实操踩坑与排查记录前面代码能用但真实环境里报错五花八门。这一章我把项目里遇到过的典型问题整理成排查路径和速查表遇到问题按顺序过一遍基本能定位到八成。4.1 invalid signature 到底该从哪查起invalid signature是出现频率最高的报错原因排列组合很多但排查有固定顺序首先确认签名用的 URL 和前端wx.config时所在页面的 URL 是否完全一致。注意是“去掉#之后”的完整 URL包括查询参数。常见错误是前端传了带 hash 的 URL 给后端或者后端做了 URL encode 而前端没有。其次确认jsapi_ticket是不是过期的或者是别的地方踢掉的。如果你有多个服务在同时调gettokentoken 会互相失效。可以在签名接口里加日志打印出参与 sign 的原文串和企微文档的示例对照格式。再次确认corpid和corpsecret用的是自建应用的不是通讯录同步助手那套。企业微信里不同用途的 secret 是分开的用错 secret 拿到的 token 可能权限不对甚至拿不到进而 ticket 也是错的。最后确认系统时间准确。timestamp如果和企微服务器的时间差太大也会签名失败。服务器最好配好 NTP 校时。提示排查阶段把wx.config的debug设成true企微会弹窗把详细错误打出来比自己在控制台猜快得多。上线前务必关掉否则真实用户会看到一堆调试弹窗。4.2 previewFile 点不动、白屏、转圈的几种典型情况点下去毫无反应八成是wx.ready还没触发就调了previewFile。要么你的 Promise 封装没 await要么 config 失败了但错误被吞了。检查wx.error有没有被触发。打开后白屏文件 URL 客户端拉不到。可能是文件服务器需要鉴权 Cookie而企微客户端在预览时是另起请求没有携带你的登录态。解决办法是后端生成一个带时效签名的临时下载链接把鉴权信息编进 URL 里而不是靠 Cookie。一直转圈文件太大或者size传错。建议大文件比如超过 50MB 的 PDF拆分或提示用户下载后再看size传真实字节数别传 0。能预览图片和 PDF但 Word 不行有些版本对 Office 文档的预览支持依赖客户端组件需要用户升级企业微信到较新版本。这种情况可以退而用wx.openDocument它对文档类型的支持更宽一些。iOS 好使安卓不好使或反之URL 处理差异。iOS 的location.href在 SPA 里可能不随路由更新安卓相对正常。统一用“进入页面时实时取 URL 重新 config”可以规避大部分此类差异。4.3 常见报错速查表我把项目里遇到过的报错和对应处理整理成表方便对照报错/现象可能原因处理方向invalid signatureURL 不一致 / ticket 过期 / 拼串顺序错核对去 hash 的完整 URL检查 ticket 缓存校验拼串格式invalid url domain可信域名没配或配错后台补配可信域名并完成校验permission denied应用可见范围不含当前用户把用户加入应用可见范围config:fail参数缺失或格式错检查 appId、timestamp 是否为数字、nonceStr 是否为空预览白屏文件 URL 客户端不可访问用带签名时效的临时直链替代 Cookie 依赖预览无反应wx.ready未触发Promise 化封装并 await开启 debug 排查转圈不停文件过大 / size 缺失传真实 size大文件走下载部分格式打不开客户端版本或格式不支持升级客户端或改用 openDocument这张表我建议直接贴到项目 wiki 里新人遇到问题先查表能省下大量重复沟通。5. 体验优化与降级兜底能跑通只是第一步真到线上你还得考虑用户在非企微环境打开、文件很大、网络不好、点了没反馈这些情况。这一章讲几个提升体验的实操点。5.1 非企业微信环境的降级方案wx.previewFile只在企微客户端里生效如果用户把链接复制到普通浏览器或微信里打开直接调会静默失败。所以我前面代码里加了 UA 判断navigator.userAgent里包含wxwork才走企微逻辑否则降级成window.open或者跳到一个自建的 PDF 预览页。判断企微 UA 的关键词就是wxwork这个比判断微信的micromessenger更准因为企微 UA 里有时候也会带micromessenger。降级的时候别忘了给用户一点提示。我一般的做法是先把文件在新标签打开如果 1 秒后document.hidden还是 false说明可能被拦截了弹一个“请点击右上角在浏览器中打开”的引导层。虽然土但确实管用。5.2 大文件、缓存与 loading 体验大文件预览是体验重灾区。我的几个处理原则超过 30MB 的文件优先让用户下载而不是内嵌预览预览前给一个明显的 loading 遮罩因为从点击到原生预览页弹出可能有几百毫秒延迟没反馈用户会以为没点到然后狂点size传准进度条才正常。缓存方面如果你用 hash 路由同一个页面反复进出会重复触发 config。虽然我做了 Promise 缓存但如果你在路由切换后又需要新的签名因为 URL 变了虽然只是 hash 变但严格来说去 hash 后可能一致可以按“去 hash 后的 URL”做缓存 key不同 key 各自保留一份签名避免反复请求后端。另外记得处理用户快速连点的情况。加一个请求锁预览调用进行中就忽略后续点击不然可能弹出多个预览页用户返回时一脸懵。5.3 需要留意的安全与合规细节最后说几个安全上的实在话。第一签名接口一定不要返回corpsecret和jsapi_ticket只返回appId、timestamp、nonceStr、signature这四个其他都烂在后端。第二临时下载链接要有时效和签名不能让任何人拿到 URL 就能无限下载企业文件尤其是涉及合同、报表这类内容的链接过期时间设短一点比如 5 分钟。第三前端不要把 access_token 之类的东西存进 localStorage签名按需向后端要。还有一个是我实际翻过车的地方文件下载直链如果用的是对象存储记得配好 CORS 和 Referer 白名单否则企微客户端拉文件时可能因为来源校验被拒。对象存储的私有读加上后端签发的临时 URL 是最稳的组合。我个人在几个企微项目里反复验证下来这套“全局单例 config 后端签名 前端封装预览 降级兜底”的组合基本可以覆盖绝大多数需求。真正花时间的从来不是写那几十行调用代码而是把可信域名、签名 URL、token 缓存这几个基础设施理顺。理顺之后新增一个预览入口就是几行代码的事。所以如果你的项目还卡在第一步别急着抄 API先把后台配置和签名这条链路单独跑通用一个最简单的“点击按钮预览固定 PDF”页面验证通了之后再往业务里接效率会高很多。
企业微信内嵌H5文件预览：Vue2.0调用wx.previewFile鉴权实战
1. 先搞清楚 previewFile 到底解决什么问题边界又在哪企业微信内嵌 H5 这个场景做过的人都知道它跟普通浏览器里跑页面完全是两套逻辑。你本地浏览器打开一切正常扔进企业微信客户端里文件点不动、预览白屏、下载无声无息这类问题几乎每个做企微自建应用的前端都遇到过。微信 JS-SDK 里那个wx.previewFile就是官方给内嵌 H5 提供的一套文件预览与下载入口专门用来在企微客户端内部打开 PDF、Word、Excel、PPT、图片这类文档而不是把用户甩到系统浏览器里再干瞪眼。这篇东西主要面向的是用vue2.0技术栈、把页面挂到企业微信里、需要做JS-SDK 鉴权并调用wx.previewFile的前端和全栈同学。我会把后台配置、签名算法、前端封装、踩坑排查整条链路都讲透代码可以直接抄。适合有一定前端基础、但第一次在企业微信里接 JS-SDK 的人也适合接过一次但老是报invalid signature想彻底搞明白原理的人。我先把结论摆在前面wx.previewFile本身调用很简单真正难的是它前面的鉴权链路和它背后的环境差异。90% 的“调不起来”问题都不在 previewFile 这一行而在wx.config有没有成功、签名算得对不对、URL 取得对不对、以及文件链接能不能被企微客户端下载到。所以别一上来就盯着 previewFile 的 API 文档看先把鉴权这条水管打通。1.1 内嵌 H5 处理文件的老办法为什么不灵在没有接 JS-SDK 之前大部分人的第一反应是用a hrefxxx.pdf download或者window.open(url)再或者window.location.href url。这三种写法在普通浏览器里都能凑合但在企业微信内嵌 WebView 里表现非常不稳定。a标签的download属性在很多内嵌 WebView 里被忽略点下去要么没反应要么直接在当前 WebView 里打开一个纯文本流把整个页面顶掉用户回都回不来。window.open更麻烦企业微信客户端会拦截弹窗有时候静默失败有时候打开一个空白页。用window.location.href跳文件流如果后端返回的是Content-Disposition: attachmentWebView 未必认可能直接渲染成一串乱码。这些方案的通病是你没法控制“预览”还是“下载”也拿不到打开成功或失败的回调用户体验完全靠猜。而wx.previewFile走的是企业微信客户端原生能力它在客户端内部用一个独立的文件预览页打开文档界面是原生的有分享、有下载、有关闭页面上下文不会被破坏用户返回后还停留在原来的 H5。这就是为什么只要目标是企微就值得专门接这一套。1.2 wx.previewFile 的定位与能力边界wx.previewFile的参数其实就几个核心是这四个url文件地址必填、name文件名带扩展名用于展示、size文件大小字节数用于显示进度、type文件类型比如 pdf、doc、xls部分版本才支持。官方文档写得很简洁但真实使用里约束不少先记在脑子里它依赖 JS-SDK 鉴权wx.config没成功后面全白搭。它只在企业微信客户端内有效普通浏览器、微信里非企微都不认。下载的url必须是客户端能直接访问的地址如果后端接口需要携带 Cookie 或自定义请求头才返回文件企微客户端拉不到。文件格式受客户端支持范围限制冷门格式可能只能下载不能预览。size虽然可选但不传的话进度条可能显示不准传了体验明显更好。知道边界之后很多“玄学问题”就有解释了白屏多半是文件 URL 拉不到没反应多半是 config 没成功一直转圈多半是文件太大而size没给对。1.3 为什么 vue2.0 项目要多做一层封装在 vue2.0 里我强烈建议不要把wx.config和wx.previewFile散落在各个页面组件里。原因很实在企微的 config 是有状态的同一个页面里重复 config 可能互相覆盖而签名接口涉及后端请求如果每个组件都去算一次签名接口调用量会爆炸缓存也没法统一管理。正确的姿势是在main.js或一个独立的utils/wx-sdk.js里做全局单例封装负责拿签名、调wx.config、暴露一个 Promise 化的ready钩子业务组件只管await这个 ready 之后再调previewFile。这样一来签名只算一次config 只调一次哪个页面要预览文件直接引封装好的方法就行。这个思路在后面第 3 章我会用完整代码展开。2. 企业微信后台与企业侧的前置配置一步都不能少很多人以为接 JS-SDK 是纯前端的事配好域名就行其实企业微信这一侧的前置配置才是第一步配错一个字段后面签名怎么算都过不去。这一章把后台配置和签名原理讲清楚理解了签名到底签的是什么你排查问题就有了方向而不是靠反复重启服务碰运气。2.1 可信域名、应用与可见范围在企业微信管理后台你要走的是“应用管理 → 自建 → 你创建的应用”这条路径。这里有几个关键字段必须配对可信域名的校验企微要求你下载校验文件放到域名根目录能通过http(s)://你的域名/文件名直接访问到才算验证成功。注意是企业微信客户端能访问到的公网地址localhost和纯内网 IP 都不行。应用主页 / 网页授权及 JS-SDK 域名这是 JS-SDK 能生效的前提必须和前端页面实际所在的域名完全一致包括协议和端口。带www和不带www是两个域名http和https也是两个域名。可见范围决定哪些成员能打开这个应用。测试阶段把所有相关同事都加进去别出现“你能进我不能进”的情况。这里有个特别容易被忽略的点如果你用的是带二级路径的部署比如页面挂在https://a.example.com/h5/下可信域名填的是https://a.example.com这没问题但如果你填成了带路径的https://a.example.com/h5很多情况下会校验失败。域名就填到域名路径交给页面自己。注意可信域名一旦改动往往需要重新走校验流程配置期间最好把域名固定下来别在开发中途换域名否则签名和 config 全要重来。2.2 JS-SDK 鉴权签名到底签了什么企业微信的 JS-SDK 鉴权本质上是把你当前页面的 URL 和一堆随机参数、票据一起做哈希生成一个签名客户端拿到后自己再算一遍对得上才允许你调 API。整条链路是这样的用corpid和corpsecret换取access_token。用access_token换取jsapi_ticket。用jsapi_ticket、noncestr、timestamp、url四个字段拼成字符串做sha1得到signature。前端拿到appId、timestamp、nonceStr、signature去调wx.config。注意拼串的顺序是有严格规定的一定是jsapi_ticketxxxnoncestrxxxtimestampxxxurlxxx字段名大小写、、一个都不能错顺序也不能颠倒。我第一次接的时候就是因为把noncestr写成了nonceStr排查了小半天。再强调一个致命细节参与签名的 url 是当前页面的完整 URL但要去掉#及其后面的部分。因为#后面是前端路由的 hash客户端根本不知道它拿到的是不带 hash 的地址。如果你的页面里带了查询参数?a1b2这些参数要保留。更稳的做法是前端主动把自己当前的 URLlocation.href.split(#)[0]传给后端后端用它算签名而不是后端自己猜。还有一个 iOS 和安卓的差异坑iOS 上 WebView 的 URL 在页面内路由切换后可能不刷新导致拿到的 URL 和签名时用的 URL 对不上。稳妥方案是每次进入需要调 JS-SDK 的页面都用当前实时 URL 重新走一次 config或者干脆把需要预览的页面做成独立 URL减少 SPA 内部路由切换带来的干扰。3. Vue2.0 工程里的完整落地实现理论和配置讲完这一章直接上代码把从引入 SDK 到封装预览方法跑通。我会按“引入 → 封装 config → 暴露预览方法 → 后端签名接口”的顺序来每一步都附上我实际项目里用的写法。3.1 JS-SDK 的引入方式与全局 config 封装企业微信的 JS-SDK 我一般直接在index.html里用 script 标签引入版本用官方推荐的 1.2.0 及以上script srchttps://res.wx.qq.com/open/js/jweixin-1.2.0.js/script为什么不 npm 装因为jweixin本质是个挂载全局wx对象的脚本企微要求它在页面初始化时加载走 script 标签最直接也避免打包工具把它 tree-shaking 掉。引进来之后window.wx就能用了。下面是我项目里的src/utils/wx-sdk.js做了单例封装import axios from axios let configPromise null function getSignature(url) { // 后端接口返回 appId、timestamp、nonceStr、signature return axios.get(/api/wx/jsapi-signature, { params: { url } }).then(res res.data) } export function initWxConfig() { if (configPromise) return configPromise const url window.location.href.split(#)[0] configPromise getSignature(url).then(data { return new Promise((resolve, reject) { window.wx.config({ beta: true, // 企业微信里调用部分能力需要开 debug: false, // 上线记得关掉 appId: data.appId, timestamp: data.timestamp, nonceStr: data.nonceStr, signature: data.signature, jsApiList: [previewFile, openDocument, getLocation, chooseImage] }) window.wx.ready(() { resolve(window.wx) }) window.wx.error(err { // 这里不要 reject 掉全局 Promise否则后续页面永远拿不到 configPromise null reject(err) }) }) }) return configPromise }这里有三个我特意处理的地方都是踩过坑总结出来的。第一configPromise做了缓存同一页面生命周期内只算一次签名避免重复请求。第二wx.error里把缓存的 Promise 清空这样失败后下次还能重试不然一次失败整个应用都废了。第三jsApiList里我把可能用到的接口都列上了但你也可以按需精简只列previewFile。3.2 预览组件的封装与调用姿势有了 config 封装业务侧调用就非常清爽了。我把它再包一层做了一个previewFile方法处理参数默认值和错误兜底import { initWxConfig } from /utils/wx-sdk export async function previewFile({ url, name, size, type }) { if (!url) throw new Error(文件地址不能为空) // 非企业微信环境直接降级 const ua navigator.userAgent.toLowerCase() if (!ua.includes(wxwork)) { window.open(url) return } const wx await initWxConfig() wx.previewFile({ url, name: name || 文件, size: size || 0, type: type || }) }组件里用起来就像普通 async 方法import { previewFile } from /utils/preview export default { methods: { async handlePreview(file) { try { await previewFile({ url: file.downloadUrl, name: file.fileName, size: file.fileSize }) } catch (e) { this.$toast(文件打开失败请稍后重试) console.error(previewFile error:, e) } } } }要点在于size尽量传真实字节数后端存文件时把文件大小一起返回别传字符串形式的 “2MB”企微要的是数字传错会导致进度条异常的。name一定要带正确的扩展名比如合同.pdf客户端靠扩展名决定用哪种预览器不带扩展名可能只给你下载。3.3 后端签名接口的实现细节签名必须在后端做原因很简单corpsecret和jsapi_ticket属于敏感凭据暴露到前端等于把整个企业的通讯录和消息能力送人。我一般用 Node.js 写一个中转接口逻辑分三步缓存access_token、缓存jsapi_ticket、计算签名。const crypto require(crypto) const axios require(axios) let tokenCache { value: , expireAt: 0 } let ticketCache { value: , expireAt: 0 } async function getAccessToken(corpid, secret) { if (tokenCache.value Date.now() tokenCache.expireAt) { return tokenCache.value } const res await axios.get(https://qyapi.weixin.qq.com/cgi-bin/gettoken, { params: { corpid, corpsecret: secret } }) tokenCache { value: res.data.access_token, expireAt: Date.now() (res.data.expires_in - 300) * 1000 } return tokenCache.value } async function getJsapiTicket(token) { if (ticketCache.value Date.now() ticketCache.expireAt) { return ticketCache.value } const res await axios.get(https://qyapi.weixin.qq.com/cgi-bin/get_jsapi_ticket, { params: { access_token: token } }) ticketCache { value: res.data.ticket, expireAt: Date.now() (res.data.expires_in - 300) * 1000 } return ticketCache.value } function buildSignature(ticket, noncestr, timestamp, url) { const raw jsapi_ticket${ticket}noncestr${noncestr}timestamp${timestamp}url${url} return crypto.createHash(sha1).update(raw).digest(hex) }两个缓存都留了 300 秒的安全余量因为access_token和ticket有效期都是 7200 秒而且同一个企业全局只有一份有效 token你在多处并发获取会互相踢掉。这也是为什么签名接口必须走服务端统一缓存不能每个请求都去拉一次。返回值组装好给前端module.exports async function handler(req, res) { const { url } req.query const token await getAccessToken(process.env.CORP_ID, process.env.CORP_SECRET) const ticket await getJsapiTicket(token) const noncestr Math.random().toString(36).slice(2, 16) const timestamp Math.floor(Date.now() / 1000) const signature buildSignature(ticket, noncestr, timestamp, url) res.json({ appId: process.env.CORP_ID, timestamp, nonceStr: noncestr, signature }) }注意url是从前端传进来的后端绝对不能用自己的域名去拼因为实际访问页面的域名可能经过代理后端和前端看到的域名不一定一致。以客户端传上来的 URL 为准这是最稳的。4. 实操踩坑与排查记录前面代码能用但真实环境里报错五花八门。这一章我把项目里遇到过的典型问题整理成排查路径和速查表遇到问题按顺序过一遍基本能定位到八成。4.1 invalid signature 到底该从哪查起invalid signature是出现频率最高的报错原因排列组合很多但排查有固定顺序首先确认签名用的 URL 和前端wx.config时所在页面的 URL 是否完全一致。注意是“去掉#之后”的完整 URL包括查询参数。常见错误是前端传了带 hash 的 URL 给后端或者后端做了 URL encode 而前端没有。其次确认jsapi_ticket是不是过期的或者是别的地方踢掉的。如果你有多个服务在同时调gettokentoken 会互相失效。可以在签名接口里加日志打印出参与 sign 的原文串和企微文档的示例对照格式。再次确认corpid和corpsecret用的是自建应用的不是通讯录同步助手那套。企业微信里不同用途的 secret 是分开的用错 secret 拿到的 token 可能权限不对甚至拿不到进而 ticket 也是错的。最后确认系统时间准确。timestamp如果和企微服务器的时间差太大也会签名失败。服务器最好配好 NTP 校时。提示排查阶段把wx.config的debug设成true企微会弹窗把详细错误打出来比自己在控制台猜快得多。上线前务必关掉否则真实用户会看到一堆调试弹窗。4.2 previewFile 点不动、白屏、转圈的几种典型情况点下去毫无反应八成是wx.ready还没触发就调了previewFile。要么你的 Promise 封装没 await要么 config 失败了但错误被吞了。检查wx.error有没有被触发。打开后白屏文件 URL 客户端拉不到。可能是文件服务器需要鉴权 Cookie而企微客户端在预览时是另起请求没有携带你的登录态。解决办法是后端生成一个带时效签名的临时下载链接把鉴权信息编进 URL 里而不是靠 Cookie。一直转圈文件太大或者size传错。建议大文件比如超过 50MB 的 PDF拆分或提示用户下载后再看size传真实字节数别传 0。能预览图片和 PDF但 Word 不行有些版本对 Office 文档的预览支持依赖客户端组件需要用户升级企业微信到较新版本。这种情况可以退而用wx.openDocument它对文档类型的支持更宽一些。iOS 好使安卓不好使或反之URL 处理差异。iOS 的location.href在 SPA 里可能不随路由更新安卓相对正常。统一用“进入页面时实时取 URL 重新 config”可以规避大部分此类差异。4.3 常见报错速查表我把项目里遇到过的报错和对应处理整理成表方便对照报错/现象可能原因处理方向invalid signatureURL 不一致 / ticket 过期 / 拼串顺序错核对去 hash 的完整 URL检查 ticket 缓存校验拼串格式invalid url domain可信域名没配或配错后台补配可信域名并完成校验permission denied应用可见范围不含当前用户把用户加入应用可见范围config:fail参数缺失或格式错检查 appId、timestamp 是否为数字、nonceStr 是否为空预览白屏文件 URL 客户端不可访问用带签名时效的临时直链替代 Cookie 依赖预览无反应wx.ready未触发Promise 化封装并 await开启 debug 排查转圈不停文件过大 / size 缺失传真实 size大文件走下载部分格式打不开客户端版本或格式不支持升级客户端或改用 openDocument这张表我建议直接贴到项目 wiki 里新人遇到问题先查表能省下大量重复沟通。5. 体验优化与降级兜底能跑通只是第一步真到线上你还得考虑用户在非企微环境打开、文件很大、网络不好、点了没反馈这些情况。这一章讲几个提升体验的实操点。5.1 非企业微信环境的降级方案wx.previewFile只在企微客户端里生效如果用户把链接复制到普通浏览器或微信里打开直接调会静默失败。所以我前面代码里加了 UA 判断navigator.userAgent里包含wxwork才走企微逻辑否则降级成window.open或者跳到一个自建的 PDF 预览页。判断企微 UA 的关键词就是wxwork这个比判断微信的micromessenger更准因为企微 UA 里有时候也会带micromessenger。降级的时候别忘了给用户一点提示。我一般的做法是先把文件在新标签打开如果 1 秒后document.hidden还是 false说明可能被拦截了弹一个“请点击右上角在浏览器中打开”的引导层。虽然土但确实管用。5.2 大文件、缓存与 loading 体验大文件预览是体验重灾区。我的几个处理原则超过 30MB 的文件优先让用户下载而不是内嵌预览预览前给一个明显的 loading 遮罩因为从点击到原生预览页弹出可能有几百毫秒延迟没反馈用户会以为没点到然后狂点size传准进度条才正常。缓存方面如果你用 hash 路由同一个页面反复进出会重复触发 config。虽然我做了 Promise 缓存但如果你在路由切换后又需要新的签名因为 URL 变了虽然只是 hash 变但严格来说去 hash 后可能一致可以按“去 hash 后的 URL”做缓存 key不同 key 各自保留一份签名避免反复请求后端。另外记得处理用户快速连点的情况。加一个请求锁预览调用进行中就忽略后续点击不然可能弹出多个预览页用户返回时一脸懵。5.3 需要留意的安全与合规细节最后说几个安全上的实在话。第一签名接口一定不要返回corpsecret和jsapi_ticket只返回appId、timestamp、nonceStr、signature这四个其他都烂在后端。第二临时下载链接要有时效和签名不能让任何人拿到 URL 就能无限下载企业文件尤其是涉及合同、报表这类内容的链接过期时间设短一点比如 5 分钟。第三前端不要把 access_token 之类的东西存进 localStorage签名按需向后端要。还有一个是我实际翻过车的地方文件下载直链如果用的是对象存储记得配好 CORS 和 Referer 白名单否则企微客户端拉文件时可能因为来源校验被拒。对象存储的私有读加上后端签发的临时 URL 是最稳的组合。我个人在几个企微项目里反复验证下来这套“全局单例 config 后端签名 前端封装预览 降级兜底”的组合基本可以覆盖绝大多数需求。真正花时间的从来不是写那几十行调用代码而是把可信域名、签名 URL、token 缓存这几个基础设施理顺。理顺之后新增一个预览入口就是几行代码的事。所以如果你的项目还卡在第一步别急着抄 API先把后台配置和签名这条链路单独跑通用一个最简单的“点击按钮预览固定 PDF”页面验证通了之后再往业务里接效率会高很多。
