企业官网建设流程全解析

• 桌面应用
• 视频
• 网络
• MCP 服务

导读

本文围绕微信视频号下载器项目中internal/workers/sph/目录下的"视频号查询 Worker"展开，完整讲解其功能定位、deploy sph命令行部署流程、cloudflare.sph*配置项含义，以及 Worker 内部两阶段接口调用与图集 ZIP 打包的实现细节。读完本文，你将掌握如何通过一条命令把视频号视频信息查询页面发布到 Cloudflare Workers，理解其访问认证模型（Bearer/Basic Auth）与可用 API，并能结合源码看懂分享链接解析、feed 信息获取和 ZIP 生成的整体调用链。

一、功能定位：无服务器的视频号视频信息查询服务

在微信视频号下载器的整体架构中，internal/workers/sph/目录承载了一个完整的 Cloudflare Worker 子项目，其作用是把"视频号视频信息查询"能力部署为一个独立的无服务器服务。该目录包含三个核心文件：

• worker.js：视频号查询 Worker 的入口，实现了全部请求路由、鉴权与上游接口调用逻辑；
• index.html：Worker 根路径返回的查询页面（含内联样式与前端脚本）；
• deploy.go：部署编排代码，负责读取共享图标、上传 Worker、配置绑定并解析 workers.dev 地址。

CLI 入口只负责读取cloudflare.sph*配置并调用sph.Deploy：

go run . deploy sph

部署成功后，即可通过浏览器访问<worker-name>.<subdomain>.workers.dev得到查询页面，也可以通过 API 形式直接调用，实现"输入分享链接 → 返回视频信息"的能力。按照 部署文档 的说明，该服务仅供自己使用，不要提供给外部，因为其依赖元宝（yuanbao）接口解析链接，存在被限制使用的风险。

二、部署前的配置准备

2.1 需要准备的配置项

deploy sph依赖cloudflare命名空间下的 5 个配置字段，模板位于 config.template.yaml：

cloudflare: accountId: "your-cloudflare-account-id" apiToken: "your-cloudflare-api-token" sphWorkerName: "sph" sphCookie: "" sphCredential: ""

各字段含义如下：

其中sphCookie需要登录 yuanbao.tencent.com 网站后获取。元宝 Web 端 Cookie 有效期约 1 个月，失效后需要重新登录获取新 Cookie，并在 Cloudflare Worker 中更新COOKIE环境变量。从部署编排源码看，这两个敏感值都以plain_text绑定注入 Worker（见 deploy.go）：

Bindings: []worker.Binding{ {Type: "plain_text", Name: "COOKIE", Text: options.Cookie}, {Type: "plain_text", Name: "ACCESS_CREDENTIAL", Text: options.Credential}, },

2.2 配置校验逻辑

deploy.go 中的normalize_deploy_options会对所有配置做 Trim 归一化，并强制校验以下必填项，缺少任意一项部署即失败：

• cloudflare.accountId未配置 → 报错未配置 cloudflare.accountId
• cloudflare.apiToken未配置 → 报错未配置 cloudflare.apiToken
• cloudflare.sphWorkerName未配置 → 报错未配置 cloudflare.sphWorkerName
• cloudflare.sphCredential未配置 → 报错未配置 cloudflare.sphCredential（凭证是强制项）
• 项目根目录为空 → 报错项目根目录不能为空

注意：sphCookie不在此处强制校验，但 Cookie 为空时 Worker 调用元宝解析接口将无法完成身份认证，实际使用中仍必须配置。

三、部署流程与产物

3.1 执行部署命令

wx_video_download deploy sph

命令入口位于 cmd/deploy.go，其Run回调调用deploy_sph()，从 Viper 配置读取上述 5 个字段后调用sph.Deploy（见 cmd/deploy.go）。部署过程中会显示两个进度阶段：

• worker：上传 Worker 脚本；
• worker_subdomain：启用并解析 workers.dev 地址。

3.2 部署编排做了什么

Deploy（deploy.go）的核心流程如下：

1. 读取共享图标：从build/icon.png读取图标字节，经build_icon_module编码为 base64 并生成export default "<base64>";形式的 ES module 字符串（见 deploy.go）。
2. 上传 Worker 脚本：通过worker.NewClient（pkg/cloudflare/worker/deploy.go）调用 Cloudflare REST API（默认https://api.cloudflare.com/client/v4），以 multipart 方式上传：
   • metadata：包含main_module = worker.js、compatibility_date = 2024-01-01和两个plain_text绑定（COOKIE、ACCESS_CREDENTIAL）；
   • 主模块worker.js（通过//go:embed嵌入）；
   • 附加文件index.html与动态生成的icon.js。
   • 部署超时 2 分钟（worker_deploy_timeout）。
3. 启用 workers.dev 子域：调用EnableSubdomain开启路由，随后GetSubdomain查询账户级子域名，最终拼出完整访问地址https://<worker-name>.<subdomain>.workers.dev。若这两个步骤失败，仅记录 warning，不影响已上传成功的 Worker（见 deploy.go）。

部署完成后命令行会输出摘要表格，包含 Worker 名称、Worker ID 与访问 URL。

四、Worker 的路由与访问认证

4.1 请求路由

Worker 入口（worker.js）在fetch处理器中按路径和方法分发请求：

CORS 头（worker.js）允许任意来源、POST, OPTIONS方法，暴露Authorization, Content-Type与Content-Disposition头，因此该 API 也可供前端或其他跨域服务直接调用。

4.2 鉴权模型

页面与静态资源是公开的，只有/api/路径需要凭证（见 worker.js）。鉴权逻辑支持两种凭证格式：

• Bearer Token：Authorization: Bearer <credential>（worker.js）；
• Basic Auth：用户名固定为wxchannels，密码为凭证本身（worker.js）。

凭证校验使用SHA-256 摘要对比而非明文比较：对客户端提供的凭证与env.ACCESS_CREDENTIAL分别计算 SHA-256，再逐字节异或比对，恒时比较避免时序侧信道（见 worker.js）。

错误语义：

• 未配置ACCESS_CREDENTIAL时返回503（access credential is not configured）；
• 凭证不匹配时返回401（unauthorized）；
• 认证失败响应带Cache-Control: no-store，避免缓存。

浏览器访问根路径时，index.html前端脚本会在本地localStorage（键名wxchannels_credential）保存凭证，之后对同源 API 的请求自动携带Bearer头（见 index.html）。因此文档中的登录方式描述为：浏览器访问时显示 HTTP Basic Auth 登录框，用户名固定wxchannels，密码填sphCredential。

直接调用 API 的 curl 示例：

# Bearer Token curl -H 'Authorization: Bearer <sphCredential>' \ -H 'Content-Type: application/json' \ -d '{"url":"https://weixin.qq.com/sph/example"}' \ 'https://<worker-name>.<subdomain>.workers.dev/api/fetch_video_profile' # Basic Auth curl -u 'wxchannels:<sphCredential>' \ -H 'Content-Type: application/json' \ -d '{"url":"https://weixin.qq.com/sph/example"}' \ 'https://<worker-name>.<subdomain>.workers.dev/api/fetch_video_profile'

五、核心 API 一：fetch_video_profile的两阶段调用链

POST /api/fetch_video_profile接收{"url": "<分享链接>"}，缺url返回400。随后fetchVideoProfile（worker.js）按两个阶段顺序执行：

5.1 阶段一：解析分享链接

调用元宝接口https://yuanbao.tencent.com/api/weixin/get_parse_result（PARSE_URL，见 worker.js），请求体为：

{"type": "video_channel_url", "url": "<shareUrl>", "scene": 1}

请求携带完整的浏览器指纹头（UA、sec-ch-ua、t-userid、x-agentid等，见 worker.js），并把部署时注入的COOKIE作为cookie头传入。响应中必须包含data.wx_export_id，否则视为解析失败。

随后从解析结果的playable_url查询参数中提取两样东西（见 worker.js）：

• token→generalToken
• eid→exportId

这两个值将作为阶段二的入参。

5.2 阶段二：获取 feed 信息

调用微信视频号预览接口https://channels.weixin.qq.com/finder-preview/api/feed/get_feed_info（FEED_INFO_URL，见 worker.js），请求体为：

{"baseReq": {"generalToken": "<generalToken>"}, "exportId": "<exportId>"}

请求 URL 附加_rid（由时间戳十六进制 + 8 位随机十六进制组成，见generateRid，worker.js）与_pageUrl参数，Referer为对应的 finder-preview 页面地址（含token与eid）。

响应错误处理较为细致（feedInfoResponseError，worker.js）：

• errCode !== 0时抛出带errCode与 HTML 去标签化后的errMsg的错误；
• data.errMsg中type != 0或存在 title/content 时，构造FeedInfoUnavailableError（code = FEED_INFO_UNAVAILABLE，status = 422），表示"视频无法播放"类业务错误；
• HTML 实体会经过decodeHtmlEntities与plainTextFromHtml清理（支持&、&#x...;、&#...;等，见 worker.js）。

该错误会以结构化字段code与details随 HTTP 响应返回给调用方（见 worker.js），前端页面据此渲染错误卡片。

5.3 响应结构

成功时返回视频号get_feed_info的原始 JSON，页面端会从中提取（见 index.html）：

• feedInfo：视频描述、createtime、封面coverUrl、picInfo图集、bgmInfo背景音乐、h264VideoInfo/h265VideoInfo中的videoUrl等；
• authorInfo：作者昵称、头像与认证图标；
• 视频地址优先级：h264VideoInfo.videoUrl>h265VideoInfo.videoUrl>feedInfo.videoUrl。

六、核心 API 二：download_feed_zip图集打包

对于图文类视频号内容，页面会展示"下载图集 ZIP"按钮，其实现为POST /api/download_feed_zip。该接口接收查询得到的 feed JSON，由extractFeedZipFiles（worker.js）提取可下载文件：

• feedInfo.picInfo中的每张图片，命名为01.jpg、02.jpg…（按索引补零）；
• bgmInfo.bgmUrl || bgmInfo.mediaStreamingUrl对应的背景音乐，命名为<bgmName>.mp3；
• 文件命名经过sanitizeZipEntryName清洗非法字符（\ / : * ? " < > |替换为_，见 worker.js）。

打包前还会先写入一个info.json（即格式化后的完整 feed 数据）。文件名兜底策略（baseFilename，worker.js）优先使用描述（截断 160 字符），无描述时使用发布时间20260101_120000格式，均无则用channels_feed。

值得关注的是，ZIP 生成逻辑是纯 JavaScript 手写实现，未依赖任何第三方库：从 CRC32 表生成（worker.js）、ZIP 本地文件头与中央目录头写入（buildZip与writeZipHeader，worker.js）到最终的 DOS 时间戳、EOCD 记录拼接，全部在 Worker 内完成，返回application/zip并带 UTF-8 编码的Content-Disposition文件名。同时 Worker 端还会根据文件实际Content-Type或 URL 后缀补全扩展名（ensureFileExtension，worker.js）。

若图集中没有可下载的图片或 BGM，接口返回400（no downloadable picture or bgm found）。

七、查询页面：从链接到下载的一站式体验

Worker 根路径返回的 index.html 是一个自包含的单页查询工具，采用经典 Model-View 结构（FeedProfileModel+FeedProfileView，index.html），主要交互流程为：

1. 粘贴视频号分享链接（如https://weixin.qq.com/sph/xxx），点击"查询"或回车触发POST /api/fetch_video_profile；
2. 结果区渲染视频卡片：可播放的视频预览（<video>+ 封面 poster）、作者昵称头像、描述、赞/爱心/转发/评论计数；
3. 视频内容提供"下载视频"按钮，图文内容提供"下载图集 ZIP"按钮；
4. 页面底部以<details>折叠展示原始响应 JSON，便于调试。

页面还实现了完整的错误呈现：凭证无效（401）提示"凭证无效，请在上方输入正确的访问凭证并保存后重试"，FEED_INFO_UNAVAILABLE则展示视频无法播放的具体原因（index.html）。

八、与 MCP 的联动

除 CLI 外，deploy sph也暴露为 MCP 工具deploy_sph_worker（sph_tools.go）。该工具不接收任何敏感参数，而是直接读取应用配置中的cloudflare.accountId、cloudflare.apiToken、cloudflare.sphWorkerName、cloudflare.sphCookie和cloudflare.sphCredential，部署或覆盖同名远端 Worker 并返回 workers.dev 地址。由于会覆盖远端 Worker，调用前必须获得用户确认；可用get_config先检查这些字段的configured状态（详见 MCP 文档）。这为通过 MCP 协议远程触发部署提供了入口。

九、常见问题与注意事项

• Cookie 失效：元宝 Web 端 Cookie 有效期约 1 个月，失效后需重新登录获取新 Cookie 并在 Cloudflare Worker 中更新COOKIE环境变量，否则fetch_video_profile阶段一将失败。
• 凭证未配置：cloudflare.sphCredential未配置时，本地部署命令会直接拒绝；即便强行部署，Worker 对/api/请求也会返回503。
• 视频无法播放：接口返回FEED_INFO_UNAVAILABLE（HTTP 422）表示 feed 信息中的业务错误（如视频已下架），前端会展示具体 title/content。
• 不要对外公开：该服务依赖元宝接口解析链接，公开使用存在被限制使用元宝的风险，文档明确要求仅供自己使用。
• API Token 权限：部署需要Workers Scripts:Edit权限；提示信息见 cmd/deploy.go。

参考资料

• 视频号查询 Worker 说明：目录结构总览与部署入口说明
• 部署命令文档：配置项、认证方式与 API 列表的权威说明
• 部署编排实现：Worker 上传、绑定注入与 workers.dev 解析
• Worker 入口实现：路由、鉴权与两阶段接口调用
• 查询页面实现：前端交互、凭证保存与结果渲染
• Cloudflare Worker 客户端：multipart 上传与子域解析的底层封装
• 配置模板：cloudflare.sph*字段默认值
• MCP 部署工具：deploy_sph_worker工具定义

• 桌面应用
• 视频
• 网络
• MCP 服务