做公众号开发的同行大概率都遇到过这种需求在图文正文里嵌一个文档附件让读者可以直接预览或下载。你可能会觉得不就是编辑文章时拖一个文件进去、生成个链接嘛有什么好研究的。但真到了开发侧就发现事情远没那么简单——公众号对素材的管控、图文发布时的链接校验、客户端 WebView 的加载策略、大文件的移动端兼容性随便哪一个环节处理不好用户看到的就不是“流畅下载”而是白屏、转圈、报错。这篇文章我打算从底层技术链路讲起一个文档附件是怎么从你的服务器一路变成公众号文章里的一个可点元素中间经过了哪些校验和转换再讲性能优化包括上传压缩、CDN 分发、正文 HTML 体积控制、移动端预览降级最后整理一批我实际踩过的问题和排查思路。目标是让正在写公众号周边系统、接入素材接口、或者在做移动端图文性能优化的朋友看完能直接拿去用。文章会涉及一些接口细节和代码片段但不会非常深入某个 SDK重心放在“原理”和“做题思路”上。1. 先搞清楚一个前提你塞进文章的那个“附件”到底是什么1.1 “插个文件”背后不是一次简单上传很多运营同学会直接把公众号后台的编辑器当成一个“Word 编辑器”来看里面能放图片、放音频、放文件好像就是一个富文本页面而已。但从开发的角度看公众号图文并不是一个纯粹由你的服务器渲染的网页它本质上是提交给微信后台的一段 HTML再统一包装成微信客户端能直接渲染的图文消息。也就是说你在编辑器里看到的“文件卡片”“文件图标”最终在图文消息 JSON 里只是一个链接节点、一个富媒体组件而文件本体早就被上传到了微信的素材系统或者存放在你自己的域名下。这里面有一个特别容易混淆的点公众号后台本身并不会把我们常用的 PDF、Word 当作一个通用素材类型来接收。官方素材接口能处理的类型基本是图片、语音、视频、缩略图这几类而普通文件你更多是靠“自建域名 超链接”、或者把文档转成图片来曲线实现。理解了这个前提之后后面所有的问题——为什么放外链会被拦、为什么 PDF 预览在微信里不稳定、为什么文件大了文章打开慢——就都有了解释。1.2 从运营封装看“卡”的根源从表面看公众号文章加载慢的锅通常会被甩给图片。我实测过不少案例一篇图文里塞了二三十张高清图首屏加载确实会变得很吃力。但在文档附件这个场景里真正让客户端崩溃或者白屏的往往不是图片而是附件本身。原因很简单附件不是“显示型”资源而是“下载/预览型”资源。用户在公众号里点开一个 PDF客户端会走 WebView 或内置预览器去拉取整个文件。文件一大网络一慢就很容易出现两个问题一是 WebView 直接白屏或内存暴涨二是用户等到失去耐心直接放弃。很多开发团队只关注“能不能把文件发出去”不关注“发出去之后用户在弱网环境下能不能顺利打开”这其实已经脱离了功能交付进入了性能优化的范畴。所以在讨论任何 API 和代码之前我建议先建立一个认知附件嵌入工作的完整链路 文件生产上传 资源分发 图文 HTML 组装 客户端渲染 弱网降级。后面所有技术细节都是围绕这条链路展开的。2. 底层链路拆解素材、票据、URL 和图文 HTML2.1 入场券access_token 的获取与缓存无论是上传素材、创建草稿、还是发布图文你的服务器首先要拿到一个凭证access_token。这个 token 可以理解为公众号后台颁发给你的一把临时钥匙每次调用接口都要带着它。access_token 的获取本身不复杂请求微信的 token 接口传入 appid 和 secret 即可。但有一个很关键的细节access_token 的有效期只有 7200 秒而且每天获取次数是有限制的。如果你把获取逻辑写成“每次调用接口之前都去拿一次”大概率会在流量稍微上来的时候把配额打满然后所有素材上传和发文任务全部报错。所以正规做法是在服务端启动时或定时任务里调用 token 接口获取凭证。把 token 放到 Redis 或内存缓存里设置过期时间 7000 秒左右。每次请求素材接口时先从缓存取取不到再重新获取并回填缓存。这里顺带说一个并发场景如果多个工作进程同时发现 token 过期就会同时去刷新导致请求冲突或拿到不同的 token。稳妥的办法是加一个分布式锁或者像 Java 里的双重检查锁那样只让一个线程去刷新其余线程等它完成。这不是微信特有的问题但在我看过的不少项目里恰恰是这种基础细节导致线上发布偶发失败。2.2 把文件交给微信素材上传接口与两类素材拿到 token 之后接下来就是把附件交到微信手里。官方接口最常用的是素材管理里的上传接口大致长这样POST https://api.weixin.qq.com/cgi-bin/material/add_material?access_tokenACCESS_TOKENtypeimage参数里type决定了你要上传的是图片、语音、视频还是缩略图。表单里带上文件字段微信会返回一个media_id部分素材类型还会返回一个url。这里必须区分“临时素材”和“永久素材”。临时素材的有效期是 3 天一般用于客服消息、临时性的多媒体回复永久素材则长期保存适合图文内容里的图片、封面等。但要注意这个接口并没有为“通用文件”开放一个typefile的选项所以如果你就是想传一个 PDF 过去直接走这个接口是行不通的。那开发里常见的做法是什么第一种把 PDF 转成一张或一组图片再用image类型上传。这种方案最符合微信的生态约束图片可以稳定出现在正文里也不会触发外链安全性问题。第二种把文件存到自己的对象存储或服务器上然后在图文正文里通过超链接、小程序或者其他方式展示。但这种方式需要处理域名校验、CDN 分发、签名时效等一系列问题。我不建议把“上传素材”理解成“把文件传上去就完事”因为微信返回的media_id只是素材库里的一条记录它不等于正文里能直接用的 URL。真正的图片链接是在你上传图片素材后返回的url字段中拿到的或者是在图文提交之后由微信系统帮你转换出来的。后面这句话很关键你在图文正文 HTML 里写的图片地址不能是一个普通外域地址最好直接使用微信素材库返回的地址否则在提交草稿的时候很可能会被校验逻辑拦下来。我经常用下面这段逻辑去跑上传流程def upload_image(access_token, file_path): url fhttps://api.weixin.qq.com/cgi-bin/material/add_material?access_token{access_token}typeimage with open(file_path, rb) as f: resp requests.post(url, files{media: f}) data resp.json() if data.get(media_id): return data[media_id], data.get(url) # 这里要记录错误码后面排查用 raise Exception(fupload failed: {data})要注意这个大文件上传请求是同步的。如果文件几十上百 MB网络又不太稳定很容易超时。所以我的建议是在上传之前先做一次文件压缩或者把上传动作放到后台任务队列里执行不要放在用户请求的同步链路上。2.3 从 media_id 到正文里真正能用的链接很多第一次对接公众号接口的开发者会有一个疑问为什么我费劲上传拿到一个 media_id结果创建图文的时候根本不传 media_id反而要我传一段 HTML这是因为图文消息的content字段本质上是一段富文本 HTML微信会解析这段 HTML 里的图片节点并对图片 URL 做二次校验。media_id是素材管理维度的一个索引而图文正文里真正渲染出来的是一个可访问的图片地址。如果你用编辑器上传图片后台会在content里生成一个形如https://mmbiz.qpic.cn/...的链接如果走开发接口你也需要把图片的 URL 组装到content里。举个例子一段最简单的正文可能是section p请查看下方附件/p pimg srchttps://mmbiz.qpic.cn/xxxx //p pa hrefhttps://your-cdn.example.com/report2025.pdf点击下载文档/a/p /section然后通过 draft/add 接口提交微信再对这段 HTML 做压缩、清洗、转存最终生成用户手机上的图文消息。这里有一个很容易被忽略的性能点微信会对图文 HTML 中的图片做转存和压缩但如果你的原图已经很大这个压缩不一定能把体积降到理想状态。而且图片 URL 如果不稳定或域名不合法在提交阶段就可能报错。所以我在组装 HTML 时习惯先做一次“资源自检”循环检查所有img标签的 src、所有a标签的 href确认它们可以访问、大小可控再提交发布。2.4 提交草稿与发布时的校验链路公众号的发布流程目前官方推荐的是“草稿 发布”模式也就是先建草稿拿到 media_id 或 article 数据再调发布接口。整个链路大致是上传素材拿到图片 URL。组装正文 HTML调用 draft/add 创建草稿。系统返回草稿的 media_id。调用 freepublish/submit 提交发布拿到 publish_id。轮询发布状态直到最终成功。在这个链路里最容易出问题的不是上传而是第 2 步的 HTML 校验以及第 4 步的发布状态轮询。你会发现同样的链接在这台电脑上测试没问题换个账号、换个域名就报“链接内容不属于当前公众号”。这个问题的背后是微信对“内容来源”的强校验如果你在正文里塞了外部链接并且这个外部链接指向了非当前公众号所声明的域名系统就会认为这条消息存在风险。所以我的经验是能用微信素材库解决的资源千万不要省事放到外部 URL 上尤其是图片、缩略图这类需要稳定展示的内容。真正的文件下载链接也尽量通过合法的业务域名配置来覆盖。3. 附件嵌入的三种主流形态图片化、外链、小程序3.1 方案 A把文档渲染成图片用图文原生能力承载这是一个非常稳、但工程上稍显粗暴的方式。思路是把 PDF、PPT、Word 每一页渲染成一张长图或方图然后按顺序插入到图文正文里用户看图就像在看文档。优点很明显微信对图片的兼容性最好不挑手机型号、不挑内核版本。图文自带懒加载和图片压缩只要单张图控制在合适范围内体验会比较顺。不需要配置业务域名也不涉及外链校验。缺点也很明显多页文档会变成大量图片HTML 体积和请求数量都会上升。文字无法搜索清晰度也可能被压缩算法削弱。如果文档有几十页用户翻起来会很累而且图片流加载在弱网环境下依然可能卡顿。我在实际项目里一般把 Word 或 PDF 渲染成图片后单张宽度控制在 1080px 左右图片格式用 JPEG如果文字是深色浅底清晰度其实还好特殊场景才用 PNG。这里要说一个坑很多人以为渲染成图片就万事大吉但图片体积没控制好一篇文章塞了二三十张 2MB 的大图用户打开的时候依旧白屏。无论原始来源是文档还是图片最终都要回到“控制体积”这条规则上。3.2 方案 B自建域名直链加签名以“下载/预览”形式嵌入第二种方案更接近传统“附件”概念文件放在自己的 OSS、COS、S3 或服务器上生成一个可下载或可预览的 URL然后通过文章的a标签把它嵌入进去。这个方案的优势是文件类型不受限你可以放 PDF、Word、Excel、ZIP甚至是一个大的数据包文件更新时只要替换存储对象即可不用重新生成整个图文。同时你可以在服务端记录下载次数、用户身份、来源渠道做更精细的数据分析。但代价也很直接你必须为外链的合规、稳定和安全负责。公众号文章里的外链会被微信系统做内容检查如果目标域名没有在公众号后台的业务域名里配置或者链接内容与公众号主体没有明确关联用户点击时会看到“链接内容不属于当前公众号”这类提示体验非常糟糕。我之前搭过一套文件服务大概的做法是# 生成带签名的下载 URL过期时间 30 分钟 from urllib.parse import urlencode import hashlib, time def sign_url(object_key, expire_seconds1800): expires int(time.time()) expire_seconds raw f{object_key}-{expires}-{secret} sign hashlib.md5(raw.encode()).hexdigest() query urlencode({expires: expires, sign: sign}) return fhttps://your-cdn.example.com/{object_key}?{query}签名 URL 可以防止文件被任意盗链也能让你统计到每次点击来源。但注意签名过期时间不要设置得太短否则用户转发到群里再点链接就失效了也不要设置得太长否则 CDN 缓存和盗链风险都会上升。一般我按 30 分钟到 2 小时来设计同时在前端做一个“过期重新生成”的兜底。方案 B 的另一个细节是域名校验文件。在公众号后台配置业务域名时需要把一个校验文件放到域名的根目录下。很多同学配置完之后就不管了结果域名到期、服务器路径变动、校验文件被误删线上外链一下就全废了。这块应该纳入自动化监控。3.3 方案 C小程序云开发承载文档附件第三种做法是把附件放到小程序云开发里然后在公众号文章里插入一个小程序卡片通过小程序页面来承载附件列表、在线预览和下载。这算是我个人比较推荐的一种“重体验”方案。它的优势在于用户点击卡片后会进入一个受控的小程序页面你可以结合用户身份做权限控制也可以调用小程序的云存储来存放大文件并通过小程序自带的wx.openDocument打开文件。这个 API 对 Office、PDF 的兼容性比 WebView 要好很多至少在移动端不会出现白屏崩掉的问题。代价是开发量比较大。你需要维护一个小程序工程处理文件列表、登录状态、下载逻辑、打开逻辑公众号图文到小程序的跳转也要提前在微信公众平台关联小程序。如果团队本来就有小程序这个方案很顺手如果只是为了一个附件功能去养一个小程序我通常会劝退。3.4 选型建议按文档类型和用户场景决策三种方案没有绝对好坏关键看文档属性和用户场景。我这里整理了一张对比表扩展开发时可以按这张表快速对号入座方案文件类型限制弱网友好度开发成本适用场景图片化适合 PDF/PPT文字会扁平化中图片多时需要懒加载低转图后直接塞正文临时活动文档、图文混排、预览类场景自建域名直链几乎不限ZIP 也能放依赖 CDN 和文件大小中需要签名、CDN、域名校验下载类物料、数据包、工具资料小程序云开发不限小程序 API 支持更多格式高受控原生预览高需要小程序配套会员资料、永久资料库、需要登录鉴权的场景选型时还要判断文档的生命周期。如果是“一次性发布会资料”图片化方案足够如果是需要持续更新、会被用户反复下载的固定文档自建域名直链更灵活如果文档内容敏感必须知道谁在看那就别偷懒直接上小程序或自建网页鉴权系统。4. 性能优化从文件生产到用户点击每一环都要较真4.1 上传侧的压缩、转码与队列化公众号图文里的附件真正让用户崩溃的通常不是排版代码写得差而是资源体积失控。性能优化的第一道关口应该在文件生产环节就开始。先拿图片举例。公众号素材接口对图片有大小限制但就算只是几 MB 的图片在移动端加载也足够慢。我的习惯是先把图片做一次统一压缩宽度按 1080px 处理质量系数根据图片内容浮动文字截图类图片用 85% 的 JPEG 质量照片类再降一点。这个步骤可以通过一个定时任务批量处理不必在请求链路中临时做。文档类的附件更需要做“预压缩”。PDF 文件体积过大我会先用 Ghostscript 做一次优化gs -sDEVICEpdfwrite -dCompatibilityLevel1.4 -dPDFSETTINGS/ebook \ -dNOPAUSE -dBATCH -sOutputFileoptimized.pdf input.pdf这个命令会把 PDF 里的高清图片降采样、去除冗余元数据适合不需要打印精度的在线阅读场景。实测下来一个 30MB 的 PDF 处理完可能只有 5MB 左右对移动端加载的改善非常明显。这里我想顺势提一嘴内存管理。如果你用脚本语言写批量转码任务很容易图省事把整个文件一次性读进内存。几十个文件同时处理内存直接打爆。不管是 Python、Go 还是你听过的 Julia 社区里那套性能优化经验核心逻辑都一样尽量用流式读取、对象复用、分批释放资源。我在实际项目里就踩过一个 PDF 转图片的 worker 进程起初每处理一页就新建一个大对象跑两个小时内存占用飙到 2GB改成对象池和流式处理后内存稳定在 300MB 以内。别小看这个公众号发布任务往往是定时批量跑内存峰值一高整个服务都会被拖垮。另外上传动作本身也应该“异步化”。不要写一个同步接口让用户上传完大文件、等微信返回素材 URL、然后再组装图文。我的做法是先把文件扔到对象存储回调任务队列里做压缩、转码、上传素材最后再通知前端完成。这样整个流程的失败重试也能独立控制。4.2 存储与分发CDN、缓存策略与签名时效文件从你的源站出去接下来就得靠 CDN 和缓存策略接住用户的访问压力。很多人对 CDN 的理解仅限于“加速”但实际工作中CDN 更重要的价值是“扛量”和“保底”。如果你的文件源站是一台普通云服务器没有做 CDN那用户每一次下载都会直接打到源站。一次活动如果有几万人同时点下载源站带宽和连接数瞬间就会被打满之后所有人都开始转圈。正确做法是文件对象存储 CDN 回源把下载压力分散到边缘节点上。缓存策略要区分文件类型和更新频率。我的习惯是资源类型Cache-Control说明图片素材一年内容基本不变适合长缓存PDF 文档短缓存或版本化文档可能更新缓存太久会拿到旧版签名临时链接不设长缓存链接过期后缓存反而影响回源HTML 动态页不缓存或极短需要实时校验权限文件更新是个大坑。这里直接说结论不要试图让用户“自动拿到最新版”而把缓存设得很短正确的做法是把文件版本号放进文件名或路径里。也就是说report.pdf更新后应该生成report_v2.pdf而不是覆盖旧文件然后在相同 URL 上更新内容。这样 CDN 和客户端缓存都能精确命中不存在“用户拿到旧文件”的问题。签名时效和 CDN 缓存有一点冲突。如果你的 CDN 缓存了某个签名 URL 的响应但源站明确告诉它“这个 URL 已失效”中间件会去回源校验。问题在于有些 CDN 会忽略查询参数导致所有带不同签名的请求都命中同一份缓存。这时你需要在 CDN 配置里开启“忽略查询参数”开关或者让签名信息放在路径里而不是参数里。这个细节很容易被忽略但排查起来非常折磨人。4.3 图文正文渲染优化减请求、控体积、延迟加载用户真正看到图文的加载体验是由正文 HTML 的质量决定的。这里有几个优化点从我处理过的公众号项目里总结出来。第一控制正文里的图片数量。公众号图文的 HTML 会包含大量图片节点客户端加载时会对这些图片做并发请求。请求并发数有限每个请求都要排队图片越多首屏就越慢。我一般会把单篇文章的图片总数控制在 15 张以内如果必须放很多附件预览图那就用“首屏之外懒加载”的思路来拆分不要让所有图片都在首屏一起加载。第二避免使用 Base64 内嵌图片。有些开发者在生成 HTML 时图省事把图片转成 Base64 直接塞进 src结果整篇 content 可能有几 MB 的字符串发布后客户端解析 HTML 就要解析好几秒。正确的做法永远是先上传到素材拿到 URL 后再引用。第三为移动端做渐进式加载。一个文档如果是很长的一篇 PDF不要指望用户在公众号里从头滑到尾。我更建议在正文里放一个“摘要 预览图”同时提供“下载原文件”按钮。预览图只展示前几页点击后再按需加载更多。这种做法既保住了公众号文章的阅读体验又避免了单次下载大文件造成的卡顿。我还处理过一个很有意思的案例一份 80 页的 PDF 资料如果不做拆分直接放链接用户打开预览器基本是白屏后来我把前 5 页做成图片预览再把完整 PDF 放到自建域名直链打开率和下载完成率都明显提升。原因不是文件变了而是用户先看到了内容有了下载的意愿自然愿意多等几秒。4.4 监控与数据反馈让附件模块可观测性能优化不能靠猜必须靠数据。我每做一个附件模块都会在一开始就埋好日志和监控不然后期出了问题根本不知道是源站带宽不够、CDN 缓存失效还是微信客户端兼容性问题。最基本的监控字段至少要有这几类上传耗时、文件大小、压缩前后体积比。素材接口的返回码和耗时分布。附件下载的 UV、PV、成功数、失败数。CDN 命中率、回源带宽、平均首字节时间。客户端上报的预览白屏率、崩溃率。日志格式不用太复杂关键是把时间、业务 ID、请求源、耗时记下来。我一般会在附件下载接口里打一条类似这样的日志[download] file_idf_20250101 status200 size1523456 cdn_hit1 ttl213ms uaWeChat这些日志配合错误码能很快定位问题。比如下载失败率突然升高先看是不是 CDN 配置被改动过如果错误集中在某个微信版本就要考虑是不是 WebView 内核升级带来的兼容问题。这里可以顺带提一个进阶玩法用大模型做文件摘要。既然文档已经传到你的服务器上你完全可以调类似 deepseek api 的服务为 PDF 生成本文摘要和关键结论然后把摘要放在图文前面原文件作为附件放后面。一方面提升了正文价值另一方面用户可以先读摘要、再决定要不要下载变相降低了无效下载带宽。我自己试过效果不错但要注意把模型调用放到异步任务里不要影响主链路的响应速度。5. 公众号文档附件场景的踩坑实录与排查速查表5.1 “发布失败 / 链接内容不属于当前公众号”怎么处理这是公众号图文开发里我遇到最多的问题之一。表面上是发布接口返回失败实际上往往是微信对正文 HTML 里的外链进行了来源校验发现链接域名和你当前公众号的主体没有绑定关系。排查步骤可以按这个顺序来检查正文里是否有外链。先通读一遍 content 的 HTML 源码把所有a标签和iframe标签拉出来看看。如果外链域名是你自己的去公众号后台确认是否已经配置到“业务域名”里。配置的时候需要放校验文件到域名根目录。检查链接是否为 HTTPS。微信对 HTTP 外链的容忍度很低能换 HTTPS 就换 HTTPS。如果链接是临时生成的签名 URL确认签名有没有过期、参数是否被截断。对于无法合法配置的域名不要硬塞直接改走图片化方案或小程序方案。我这里特别提醒一点不要试图用“短链跳转”之类的手段绕过校验。微信对这类行为的识别能力很强一旦被判违规风险是账号层面的完全没有必要。5.2 素材接口高频报错40007、45009、41005素材上传和图文发布阶段错误码是最直接的排查线索。我整理了一张高频错误码速查表错误码含义分析常见处理方式40007media_id 不存在或已被删除检查是否先上传后立即使用确认 media_id 来源41005缺少媒体文件或文件为空检查 multipart 表单字段名是否叫 media文件是否真实存在45009接口调用超过频率限制检查 access_token 刷新和素材上传的调用频率加队列限流45001素材文件大小超限压缩文件后再上传48001api 功能未授权确认公众号类型和接口权限是否匹配53010链接内容不属于当前公众号去业务域名配置或改用图片化方案这堆错误里45009 是最容易被忽略的。公众号接口调用频率有严格的配额限制如果业务流量上来又没有对上传做排队很容易触发。解决办法就是在调用层统一加一个“请求闸门”把同一批素材上传任务放到队列里按官方频率限制匀速调度。5.3 移动端 PDF 预览白屏与内存暴涨公众号文章里贴 PDF用户点击打开时iOS 和 Android 的表现差异很大。iOS 一般会唤起内置 Quick Look小文件问题不大Android 各机型 WebView 内核不一致遇到大 PDF 或非标准编码文件白屏、闪退、内存暴涨都很常见。实战里我的降级策略是这样的文件超过 10MB默认不让微信内预览而是提示“复制链接到浏览器打开”或者引导下载。文件在 5MB 到 10MB 之间提供“预览 PDF”和“下载 PDF”两个按钮预览页用 iframe 嵌入。文件小于 5MB可以大胆用微信内置预览器但也要加一个“如果预览失败请下载”的兜底文案。如果是给 C 端大众用户看的文档尽量用图片化方案彻底绕开预览器兼容性问题。还有一个冷门但真实的坑PDF 文件里的字体编码不规范或者 PDF 是由某个特殊软件导出的预览器会直接卡死在“加载中”。这种问题没法从代码层面修复只能靠“下载后阅读”兜底。5.4 附件更新了用户拿到的还是旧文件我之前在自建域名直链方案下遇到过这个场景PDF 文件在 OSS 里覆盖更新了CDN 缓存也主动刷新了但用户在公众号里打开看到的还是旧内容。后来一查问题不出在 CDN而在于微信客户端对同一个 URL 做了较长周期的本地缓存加之公众号文章一旦发布正文里的链接地址就不会再变了用户下次打开读到的还是那次发布时生成的内容。解决思路有两个一是更新文档时不要覆盖原 URL而是生成新文件并重新发布一篇文章。这在严格意义上不算“更新附件”而是“更新内容”对公众号体系来说是最稳定的方式。二是如果你确实希望在同一个链接上做版本切换那就在文件路径里加入版本号比如/report_v2.pdf并且让正文中的链接指向一个你自己的跳转接口由接口 302 重定向到当前版本。这样以后你可以随时切换版本不需要重新发布公众号文章。我觉得在实践中第一种方式最省心。公众号文章本身就有追溯和更新需求与其去对抗缓存不如顺应平台的“版本即内容”规则。5.5 一个可复用的开发调试清单最后分享一份我在上线公众号附件功能之前会完整走一遍的检查清单不一定适用于所有项目但能帮你避开大多数低级事故access_token 是否走缓存刷新逻辑是否加了锁。素材上传是否走异步任务失败是否有重试机制。上传前文件是否压缩过图片宽度是否控制在 1080px 附近。图文 content 里是否还有外链外链域名是否已经配置到业务域名。图片来源是否全部使用微信素材返回的 URL有没有残留 Base64 图片。CDN 是否开启文件资源是否设置了合理的 Cache-Control。下载链接是否有签名签名过期后的兜底流程是否可用。是否在日志里记录了文件大小、下载耗时、CDN 命中率。移动端预览是否做了 5MB / 10MB 的分级降级策略。是否准备了一个小于 1MB 的测试附件用来快速验证整条链路。这套清单我已经用了很长时间。每次新建一个公众号相关项目我都会先照着做一轮基本能省掉后续一半的排障时间。最后再唠叨一句附件功能看上去是个小需求但它跨了文件存储、CDN、微信开放平台、移动端渲染几个大领域任何一个环节掉链子用户感知都非常直接。与其等线上出问题再救火不如在方案里就把“弱网降级”和“可观测性”写进需求里这才是做工程该有的习惯。