al-folio 404 页面定制指南：从 Jekyll 前端元数据到站内重定向与链接健康检查

• 前端

本篇技术指南围绕 al-folio 主题的 404 错误页（_pages/404.md）展开，讲解如何用 Jekyll 前端元数据（Front Matter）定义“页面未找到”页、通过自动重定向把访客带回首页，并配套说明主题内置的重定向机制、CI 断链检查与静态站点下的 404 页面约束。读完你将掌握：al-folio 中 404 页的完整文件构成与每个字段的语义、如何利用redirect机制做站内跳转（含博客/项目示例），以及如何借助自动化工具保证站点不存在“死链”进入该页面。

一、404 页面在 al-folio 项目中的位置与角色

al-folio 是面向学术工作者的 Jekyll 主题。与绝大多数静态站点生成器一样，它通过一个名为404.html的特殊路由来兜底所有不存在的 URL。在主题的 v1.x 版本中，这个页面由站点仓库本地文件_pages/404.md提供，是整个站点的“最后一道防线”：

--- layout: page permalink: /404.html title: "Page not found" description: "Looks like there has been a mistake. Nothing exists here." redirect: true --- You will be redirected to the main page within 3 seconds. If not redirected, please go back to the home page.

从文件结构上看，_pages/目录存放站点的核心页面（关于页、博客、项目、出版物等），404 页与它们并列；docs/CUSTOMIZE.md的目录树一节也明确标注了📄 404.md: 404 page (page not found)的职责。这意味着定制 404 页不需要深入主题内部代码，只需修改这一个 Markdown 文件的前端元数据与正文即可。

二、逐字段拆解前端元数据：404 页的“配置面”

404 页的所有行为都由 YAML Front Matter 驱动，每个字段都值得单独理解：

其中permalink是最关键的一环：静态托管服务（如 GitHub Pages、Netlify、Vercel）约定俗成地会把站点根目录下的404.html当作“未找到”响应页。只要 Jekyll 把该页面渲染到/404.html，部署后所有无法解析的 URL 都会落到这个页面，而不是显示平台自带的默认错误页。

redirect: true则是 al-folio 提供的轻量级“软重定向”开关：当它被置为true时，配合正文中的提示文案与自动跳转脚本，访客会在约 3 秒后被带回主页；脚本失效时，正文中的“回家链接”依然保证用户可以手动返回。这种“自动 + 手动”的双保险设计，正是学术站点在误输入 URL、旧链接失效等场景下保住用户不流失的常用手段。

三、正文中的重定向实现：自动跳转与回退链接

404 页正文只有两行，却完整覆盖了两种返回路径：

You will be redirected to the main page within 3 seconds. If not redirected, please go back to the home page.

第一句告知用户“3 秒内自动跳转”；第二句提供手动回退——一个指向主页的链接。注意这里的链接并非硬编码，而是 Jekyll Liquid 模板表达式：

{{ site.baseurl | prepend: site.url }}

它把_config.yml中配置的url（如https://alshedivat.github.io）与baseurl（如/al-folio）拼接成完整主页地址。这样做有两个直接好处：

1. 子路径部署无痛：当站点挂在子路径（baseurl: /al-folio）下时，链接依然指向正确的首页，不会因目录层级变化而失效；
2. 本地预览与线上行为一致：jekyll serve本地开发与 CI 构建产物共用同一套模板解析，避免硬编码地址带来的环境差异。

从实现角度看，这与主题在博客列表页_pages/blog.md中对文章链接的处理方式一脉相承——那里使用relative_url过滤器生成站内相对链接，而 404 页使用url+baseurl拼出绝对链接，目的都是为了在任意部署环境下保持链接可用。

四、主题的通用 redirect 机制：不止 404 页

redirect并非 404 页独有，它是 al-folio 的一个通用 Front Matter 约定，广泛用于“从旧地址跳到新地址”“跳转到站内资源”等场景，仓库中有多个可直接参考的实例：

博客文章重定向：_posts/2022-02-01-redirect.md演示了把一篇文章重定向到站内 PDF 资源：

--- layout: post title: a post with redirect date: 2022-02-01 17:39:00 description: you can also redirect to assets like pdf redirect: /assets/pdf/example_pdf.pdf ---

项目重定向：_projects/3_project.md演示了把项目卡片重定向到外部站点：

--- redirect: https://www.wikipedia.org/ ---

两种取值方式的分流逻辑体现在博客列表模板_pages/blog.md中（对应第 131–140 行）：

{% if post.redirect == blank %} <a class="post-title" href="{{ post.url | relative_url }}">{{ post.title }}</a> {% elsif post.redirect contains '://' %} <a class="post-title" href="{{ post.redirect }}" target="_blank">{{ post.title }}</a> <!-- 外链图标 --> {% else %} <a class="post-title" href="{{ post.redirect | relative_url }}">{{ post.title }}</a> {% endif %}

• 未设置redirect：正常链接到文章页本身；
• 值包含://（绝对外链）：以target="_blank"新窗口打开，并附上一个外链跳转图标；
• 值为站内相对路径：经relative_url过滤器解析成站内链接。

对比之下可以更清楚地理解 404 页的redirect: true：布尔值true是“启用自动回跳”的语义开关，配合正文中的 Liquid 链接完成导航；而字符串形式的redirect则是“直接跳到指定目标”的路由声明。二者共同构成 al-folio 的站内/站外重定向能力。

五、构建、部署与本地验证 404 页

404 页随 Jekyll 构建自然产出。本地验证流程与主题其他页面完全一致：

# 安装依赖（Gemfile 已锁定全部插件，见根目录 Gemfile） bundle install # 本地预览，默认监听 http://localhost:4000 bundle exec jekyll serve

构建产物会写入_site/，404 页对应输出为_site/404.html。你可以直接在浏览器访问任意不存在的路径（如http://localhost:4000/does-not-exist）验证：

1. 是否呈现Page not found标题与描述文案；
2. 约 3 秒后是否自动跳回主页；
3. 若手动禁用了跳转脚本，正文中的主页链接是否可点击返回。

仓库的 CI 流程也印证了这套验证思路：部署后触发的broken-links-site.yml工作流会对_site/**/*.html做离线链接检查（lychee 配合--offline与--remap参数），确保站内 HTML 之间不存在断链——断链正是触发 404 页的主要来源之一；构建前的broken-links.yml则对源文件做全量链接检查，并特意将_pages/404.md列入排除项（因为它包含 Liquid 模板语法，无法被静态链接检查器直接解析）。这解释了为什么 404 页中的链接必须依赖模板变量：任何硬编码地址在 CI 检查中都是不可控的。

六、定制 404 页的实操建议

在 al-folio 中定制 404 页只需修改_pages/404.md一个文件，以下是围绕它的完整实操清单：

1. 保持路由不变：permalink: /404.html不要改动，它是被静态托管平台识别为错误页的唯一约定；
2. 自定义文案与视觉：可替换title、description与正文提示，如加入一句面向自己站点读者的话术；若需要更多样式，可以在正文中插入自定义 HTML/Markdown 块；
3. 保持重定向开关：建议保留redirect: true与 3 秒回跳提示，避免访客进入“死胡同”后流失；
4. 链接始终用模板变量：正文链接保持{{ site.baseurl | prepend: site.url }}形式，不要在 Markdown 中硬编码域名，以保证子路径部署与 CI 检查的兼容性；
5. 配合全站链接健康检查：启用/关注仓库中broken-links.yml与broken-links-site.yml两个工作流，从源头减少进入 404 页的流量。

七、小结

al-folio 的 404 页面虽然只有短短数行，却浓缩了 Jekyll 前端元数据、Liquid 模板表达式、静态托管路由约定与链接健康工程四层知识：

• 前端元数据定义页面布局、路由、标题、描述与重定向开关；
• Liquid 表达式让主页链接在任意url/baseurl组合下保持正确；
• 通用redirect机制在博客、项目与 404 页间保持一致语义；
• CI 断链检查从构建与部署两侧守护站点，尽可能减少用户落入“Page not found”的概率。

对维护者而言，理解这四层不仅能快速定制出符合个人风格的错误页，更能把握 al-folio 在链接与路由设计上的整体思路——这正是静态学术站点可用性的重要一环。

• 前端