给Hugo加上短链分享功能

2026-11-16 21:00≈ 304字≈ 2分钟

用了这么久博客,平时分享文章一直有个小问题。

有时候想把文章分享到公共平台,链接比较长,而且打开之后还是完整的网站布局。比如导航、侧栏、页脚这些东西,对自己浏览当然有用,但别人只是想看一篇文章时,其实不一定需要。

之前也考虑过单独生成一个分享页面,或者再做一套页面模板。后来想了想,没有必要。文章内容本来就是同一份,没必要为了分享再生成一份HTML。最后决定在原有 Hugo 页面上增加一个纯阅读模式,再用 Cloudflare Worker 做短链跳转,最后把整个流程接到文章页面的分享按钮上。

最后效果什么样的

image-20261116220645731

普通访问文章时,页面和之前一样,但是文章底部在RSS按钮旁边会有一个分享按钮,点击分享按钮,系统会先检查这篇文章有没有短链。

  • 已经生成过短链,就直接复用。
  • 第一次分享,就请求 Worker 创建一条短链。
  • 创建成功后复制短链。
  • 别人打开短链,Worker 查询 Cloudflare KV,再跳转到原文章的纯阅读模式。
  • 分享模式只隐藏网站外围的导航和工具,不重新生成文章页面。

大致的访问关系是这样:

 1普通文章
 2https://www.igerm.ee/essay/example/
 3
 4分享短链
 5https://www.igerm.ee/s/短码
 6
 7Worker 查询 KV
 8        |
 9        v
10原文章地址 + ?share=1

这里有个关键点:短链并不指向另一份文章,也不是把文章内容存进Cloudflare。它只保存短码和原文章路径之间的对应关系,文章仍然由 Hugo生成的静态页面提供。这样就大大节省了Cloudflare的构建时间。

一、先把文章变成纯阅读模式

Hugo 文章仍然使用原来的 URL,只是增加一个查询参数:

1https://www.igerm.ee/essay/example/?share=1

页面加载时检查 URL 有没有 share=1。如果有,就给页面根元素增加一个share-mode 标记,CSS 根据这个标记隐藏不需要的站点 UI。核心逻辑很简单:

1(() => {
2  const params = new URLSearchParams(window.location.search);
3
4  if (params.get("share") === "1") {
5    document.documentElement.classList.add("share-mode");
6  }
7})();

然后在 CSS 里针对 share-mode隐藏顶部导航、侧栏、移动端导航、页脚工具等元素。不过这里需要注意看主题实际使用的DOM 结构,否则很容易把文章正文、图片或者目录也一起隐藏掉,尤其是最近增加了说说首页,那个是把正文也放到首页里面了,然后没有详细页。

我比较在意的是,正常访问不能受到影响。因此所有隐藏规则都必须以.share-mode 为前提,没有这个标记时,原来的页面样式不变。

这种做法还有一个好处:不需要为每篇文章生成第二份 HTML。原文章URL、canonical、RSS 和 sitemap都不需要跟着改,分享模式只是同一个页面的一种显示状态。

二、用 Cloudflare Worker 做短链

我的博客本身是 Hugo静态站点,没有传统意义上的后端服务器,也不想为了一个短链功能再维护Docker、数据库或者一台常驻主机。既然域名已经在 Cloudflare 上,Worker 和KV 就足够了。

这次使用的组件很简单:

组件作用
Cloudflare Worker接收短链请求、查询映射、执行跳转
Cloudflare KV保存短码与文章路径的对应关系
Hugo继续生成和托管原文章
Cloudflare Access保护短链创建接口,限制只有我自己能创建

KV 里保存的内容可以理解为:

1key:   dit28n
2value: /essay/example/

访问:

1https://www.igerm.ee/s/dit28n

Worker 会从 URL 中取出 dit28n,到 KV查询对应的文章路径,再拼成本站文章地址,并附加?share=1,最后返回重定向。

整个过程不需要 Worker 读取文章正文,也不需要把文章内容写入 KV。KV只保存很小的映射数据。

为什么短链映射放在 KV

如果把短码直接写在 Worker源代码里,每增加一篇文章就要改代码、重新部署一次,这显然不合适。

放在 KV 里就不一样了。Worker的逻辑基本不变,新增文章时只需要增加一条映射。已经生成的短链也不会因为网站重新构建或者 Worker 重新部署就消失。

Worker 通过 SHORT_LINKS 这个 binding 访问它。KV 是独立于Hugo构建产物的云端存储,重新部署静态网站不会清空它。

Worker 还要负责安全校验

短链本质上是一个跳转入口,如果不限制目标地址,就可能变成开放重定向服务。比如有人构造一条记录,让本站短链跳到一个完全无关的外部网站,这显然不是我想要的。

所以 Worker 不能直接相信外部传入的目标URL。创建和跳转时都要校验路径,只允许本站内部的文章路径,并处理异常编码、路径穿越等情况。短码不存在时返回404,而不是随便跳转。

另外,跳转使用的是临时重定向,而不是永久301。这样以后如果确实需要调整映射,不容易被浏览器或中间缓存长期记住旧目标。

三、解决谁有权限创建短链

短链跳转可以公开,但创建短链不能公开。

如果把管理 Token 写进网页JavaScript,任何人打开开发者工具都能看到。即使代码压缩、变量改名,也不构成安全保护。因此浏览器端不能携带一个写在前端代码里的长期管理密钥。虽然吧,好像没啥用,但是免费的Access只允许50个用户使用,如果把Token放出去,那我的信用卡就要爆了…

最后决定使用Cloudflare Access 来验证身份。

Cloudflare Zero Trust 里创建了一个 Self-hosted 应用,保护的路径是:

1www.igerm.ee/api/share-links/*

Access Policy 使用Allow,只允许指定的邮箱身份通过。这样普通访客访问文章和短链不受影响,但创建接口需要先完成Access 登录。

Worker 端还会验证 Cloudflare Access 传过来的 JWT,检查签发方、应用 AUD和有效期。也就是说,不是只要请求里带一个看起来像登录成功的参数就能创建短链,Worker仍然会做服务端验证。

这里还保留了原来的 Bearer Token 方式,主要给命令行和 curl使用。它保存在 Cloudflare Worker 的 Secret 中,不放进 Hugo 配置、不进入公开仓库,也不下发到浏览器。

相关配置项可以看到:

1ACCESS_TEAM_DOMAIN
2ACCESS_AUD
3SHARE_LINK_ADMIN_TOKEN

前两个是 Access JWT 校验所需的配置,最后一个是命令行管理接口使用的Secret。

实际部署时,Secret 应该在 Cloudflare Dashboard中配置,不能把真实值写进代码或文章里。

Safari 登录回跳还绕了一点弯路

这一部分反而花了不少时间。

最初尝试在前端自己拼 Cloudflare Access 的登录地址,结果 Safari会出现空白页,Chrome 里也有过不正常的页面。后来发现 Access 实际生成的登录 URL 带有动态参数,不能简单地把 Team Domain 和/cdn-cgi/access/login 拼起来当作固定入口。

最后没有继续猜登录 URL,而是让浏览器先访问本站受 Access 保护的 API路径,由 Cloudflare 自己接管登录流程。登录完成后,再通过 Worker的一个回跳路由返回原文章。

回跳参数也不能随便信任。Worker 会检查return,只允许本站的文章路径,拒绝外部域名、协议相对地址以及/api/、/s/这类不应该作为文章返回目标的路径。这样既能回到原文章,也避免把登录回跳做成开放重定向。

最终还是利用ChatGPT搞定了配置…

四、把短链功能放到文章页面

后端和权限验证都完成后,才开始改 Hugo 前端。

分享按钮放在普通文章正文结束之后、Footer 版权信息之前,与原来的 RSS按钮放在一起,这样做的好处是不影响阅读,只有需要分享的时候才会把文章拖到最下面去找分享按钮。

前端脚本主要做几件事:

  1. 读取当前文章的 pathname,作为文章路径。
  2. 先请求公开查询接口,看看这篇文章是否已经有短链。
  3. 如果已经有,就直接复用,不重复创建。
  4. 如果没有,就请求受 Access 保护的创建接口。
  5. 创建成功后复制短链,并显示结果。
  6. 请求失败时给出错误提示,允许重试,同时避免用户连续点击造成重复请求。

这里有个容易忽略的地方:文章路径应该使用window.location.pathname,而不是把当前完整 URL原样存进去。因为分享模式本身带有?share=1,这个参数是控制页面显示的,不应该被写入 KV 的文章路径。

例如:

1const path = window.location.pathname;

中文文章路径也需要在请求 URL时正确编码,避免中文字符导致查询失败。Worker 端再进行规范化和安全校验。分享模式本身也会隐藏分享按钮。毕竟别人打开的是纯阅读页面,再显示一个分享按钮和站点工具栏就有点多余了。

五、部署与实际测试

这次改造涉及 Hugo 模板、前端 JavaScript、CSS 和 Worker。Worker 又新增了jose 依赖,用于验证 Cloudflare Access JWT,因此构建时需要先安装 npm依赖。

我其实是很烦的,但是想了半天其他方法都要写好多代码啊…就…没办法,你会发现Hugo得项目里面出现了Node…哈哈哈哈!!

Cloudflare Workers Builds 使用的构建命令调整为:

1npm ci && bash scripts/build-cloudflare.sh

部署命令是:

1npx wrangler deploy

这里仍然沿用仓库的 Git推送部署流程。代码在本地修改并提交后,推送到对应分支,Cloudflare Workers Builds 就会自动触发构建和部署,不需要再手动登录服务器执行部署命令。

最后

这次功能看起来只是文章下面多了一个分享按钮,但实际涉及的东西还不少:Hugo页面状态、Worker 路由、KV 存储、短链生成与复用、Access 身份验证、JWT校验、浏览器登录回跳,以及前端复制和异常处理。

好在不需要增加一台服务器,也没有引入数据库。Hugo 继续负责文章,Worker负责短链逻辑,KV 保存映射,Access 管理创建权限,各自做自己擅长的事情。

现在生成过的短链会保存在 Cloudflare KV 里。以后即使重新构建 Hugo 或更新Worker,映射记录也还在。同一篇文章再次点击分享时,会直接复用之前的短链,不需要每次都生成一个新的。

说到底,博客是用来写东西的。能交给 Cloudflare托管的部分就尽量交给它,不要为了一个小功能再给自己增加一套需要长期维护的服务。