Starlight 自定义 404 页面配置实战：从 splash 模板到 hero 组件

文档前端开发工具【免费下载链接】starlight Build beautiful, accessible, high-performance documentation websites with Astro项目地址https://gitcode.com/gh_mirrors/st/starlight点击查看免费下载导读本篇文章以 Starlight 官方文档仓库中真实存在的葡萄牙语版 404 页面 docs/src/content/docs/pt-br/404.md 为核心样本系统讲解在 Astro Starlight 文档站点中如何自定义页面未找到404页面。读完本文你将掌握 404 页面的自动生成机制、splash布局模板的作用、hero配置块的全部字段语义以及如何结合editUrl、lastUpdated和disable404Route等配置实现多语言站点下的友好 404 体验。一、从一个真实的 404 页面样本说起docs/src/content/docs/pt-br/404.md是 Starlight 官方文档站点的葡萄牙语巴西404 页面其完整内容如下--- title: Não encontrado template: splash editUrl: false lastUpdated: false hero: title: 404 tagline: strongHouston, temos um problema./strong Não conseguimos encontrar essa página.brVerifique a URL ou tente utilizar a barra de pesquisa. actions: - text: Ir para o início icon: right-arrow link: /pt-br/ variant: primary ---这段仅含 frontmatter 的文档页面没有任何正文 Markdown 内容因为它不需要正文——整页内容完全由 frontmatter 中的hero配置块驱动渲染。这实际上体现了 Starlight 文档站点的两个核心能力任意内容文件都可作为 404 页面只要文件名是404.md或404.mdxStarlight 就会自动将其注册为站点的 404 路由splash模板 hero配置可以完全脱离文档页的侧边栏、目录等布局用 hero 区块呈现一个独立、聚焦的错误提示页面。英文版对应文件为 docs/src/content/docs/404.md结构完全一致仅文案和链接不同链接指向/两份文件形成了多语言 404 的配对实现。二、404 路由是如何自动生成的在 Starlight 中404 页面并非需要手动在astro.config里声明路由而是由集成自动注入。在 packages/starlight/src/index.ts 中可以看到路由注入的核心逻辑if (!starlightConfig.disable404Route) { injectRoute({ pattern: 404, entrypoint: ... ? astrojs/starlight/routes/static/404.astro : astrojs/starlight/routes/ssr/404.astro, }); }也就是说当用户内容集合中存在404.md之类的文件时该文件会与注入的 404 路由模板相结合静态输出模式prerender true与 SSR 模式prerender false分别对应两个不同的路由实现packages/starlight/src/routes/static/404.astro声明export const prerender true在构建期生成404.html适用于纯静态部署packages/starlight/src/routes/ssr/404.astro声明export const prerender false在服务器端按需返回 404 响应适用于 SSR 部署packages/starlight/src/routes/ssr/index.astro 中同样会以new Response(null, { status: 404 })配合返回正确状态码。两者最终都渲染同一个 packages/starlight/src/routes/common.astro由它读取路由数据、渲染页面并包裹进Page组件中。因此你只需在内容目录中编写404.md剩下的路由与状态码处理都由框架完成。三、template: splash无侧边栏的宽版布局frontmatter 中的template字段决定页面布局风格。其取值在 packages/starlight/src/schema.ts 中定义template: z.enum([doc, splash]).default(doc),doc默认标准文档布局包含左侧导航侧边栏、右侧目录等splash宽版布局不渲染任何侧边栏适合首页、落地页或像 404 这样需要全屏聚焦的页面。splash模板对页面结构的影响在路由数据层就有体现。packages/starlight/src/utils/routing/data.ts 中hasSidebar: entry.data.template ! splash,template splash时hasSidebar为falsepackages/starlight/src/components/Page.astro 便不会渲染Sidebar slotsidebar /同时html:not([data-has-sidebar])会把内容区宽度从--sl-sidebar-width约束中释放出来扩大到67.5rem。这正是splash页面内容居中、无干扰视觉效果的来源。四、hero 配置块逐字段拆解hero是 frontmatter 中驱动页面首屏的核心配置其完整 schema 定义于 packages/starlight/src/schemas/hero.ts。对照pt-br/404.md的用法逐字段说明如下4.1title大标题title: 404类型可选字符串支持 HTML语义hero 区块的大号标题文字若不提供则回退使用页面顶层的title字段。这里显式给出404使页面核心视觉元素就是醒目的数字 404。4.2tagline副标题说明文字tagline: strongHouston, temos um problema./strong Não conseguimos encontrar essa página.brVerifique a URL ou tente utilizar a barra de pesquisa.类型可选字符串支持 HTML因此可以使用strong加粗关键词、br换行语义在标题下方以较小的字号显示的项目简介或提示文案。这里用一句休斯顿我们遇到问题了的幽默文案引导用户检查 URL 或使用搜索栏。在 packages/starlight/src/components/Hero.astro 的渲染逻辑中tagline通过set:html{tagline}注入 DOM字号由 CSSclamp(var(--sl-text-base), calc(0.0625rem 2vw), var(--sl-text-xl))控制颜色使用--sl-color-gray-2确保与当前主题色系统联动。4.3actions行动按钮组actions: - text: Ir para o início icon: right-arrow link: /pt-br/ variant: primaryactions是按钮数组每个按钮支持以下字段见 packages/starlight/src/schemas/hero.ts字段类型说明text字符串必填按钮上显示的文本link字符串必填按钮href值支持站内路径如/pt-br/或外部 URLvariantprimary/secondary/minimal按钮样式默认primaryicon内置图标名或内联svg显示在链接文字旁的图标本仓库中right-arrow是 Starlight 内置图标之一定义见 packages/starlight/src/components-internals/Icons.tsattrs对象附加到链接上的 HTML 属性如class、target等pt-br/404.md中配置的Ir para o início回到首页按钮使用primary强调样式 right-arrow图标指向葡萄牙语站点的首页/pt-br/——注意多语言站点中链接必须带上语言前缀而英文版 404 的对应配置则指向/。4.4 hero 渲染细节Hero.astro 完整演示了 hero 的渲染管线支持image字段file相对路径、dark/light双主题图片或html原始 HTML 三种形式404 页面未使用标题渲染为带idmain-content语义的h1对应常量PAGE_TITLE_ID保证可访问性锚点按钮渲染复用LinkButton组件桌面端min-width: 50rem采用7fr 4fr双栏网格移动端单栏居中——这些响应式规则都定义在Hero.astro内联样式层starlight.core中。五、editUrl: false与lastUpdated: false的含义frontmatter 中这两行同样有明确语义editUrl: false关闭本页的编辑此页链接。404 页面本质是错误提示页指向源码编辑链接没有意义因此显式禁用。字段定义见 packages/starlight/src/schema.ts 中的editUrl: z.union([z.url(), z.boolean()]).optional().default(true)——默认为true继承全局editLink.baseUrl配置传false可逐页关闭。lastUpdated: false关闭本页的最后更新时间显示。同理错误页不应展示时间戳。这两个字段展示了 Starlight 的全局配置可被页面级 frontmatter 覆盖的设计原则全局开启的能力可以在任意单页上按需关闭。六、多语言站点的 404回退与翻译系统Starlight 的多语言站点中每个语言目录都可放置自己的404.md。若某个语言没有提供框架还有一层内置兜底各语言翻译文件如 packages/starlight/src/translations/en.json、packages/starlight/src/translations/pt.json中的404.text键定义了默认 404 提示文案该键在 packages/starlight/src/schemas/i18n.ts 中声明并在 packages/starlight/src/global.ts 中通过Astro.locals.t(404.text)暴露给全局模板。因此自定义 404 页面的推荐做法是优先用hero块构建品牌化的 404 体验如本样本所示把翻译系统保留为未覆盖语言时的兜底方案。七、扩展如何完全关闭内置 404 路由如果你希望完全接管 404 处理例如在边缘层自定义可以在astro.config.mjs的 Starlight 配置中设置starlight({ title: My Docs, disable404Route: true, // ... })当disable404Route为true时packages/starlight/src/index.ts 中的injectRoute注入逻辑会被跳过不再生成内置 404 页面。反之默认情况只要你的内容集合里存在404.md它就自动成为站点 404 页。八、实践要点小结对照pt-br/404.md这个真实样本自定义 Starlight 404 页面时可以沉淀以下经验文件命名与位置在每个语言目录下放置404.md如docs/src/content/docs/pt-br/404.md无需手动配置路由布局选择template: splash去掉侧边栏让错误提示更聚焦需要标准文档布局时保留默认doc内容即配置整个页面通过hero.title、hero.tagline、hero.actions驱动无需撰写正文 Markdown回链要带语言前缀多语言站点中按钮link指向对应语言首页如/pt-br/英文根站则指向/关闭无意义的 UIeditUrl: false、lastUpdated: false避免在错误页出现编辑链接与时间戳兜底机制未提供 404 文档的语言会自动回退到翻译文件中的404.text默认文案。相关实现与配置文件的完整路径索引index.ts404 路由注入、static/404.astro 与 ssr/404.astro双模式路由、schema.tstemplate/editUrl/lastUpdated字段定义、hero.tshero 完整 schema、Hero.astro渲染实现、Page.astrosplash 布局影响与 404 页面的 pagefind 排除逻辑。赞分享文档前端开发工具【免费下载链接】starlight Build beautiful, accessible, high-performance documentation websites with Astro项目地址https://gitcode.com/gh_mirrors/st/starlight点击查看免费下载相关推荐2019 年 GraphiQL 第二次工作组会议议程解析插件系统、可复用 UI 包与 LSP/编辑器技术选型的历史起点2019 年 GraphiQL 第二次工作组会议议程解析插件系统、可复用 UI 包与 LSP/编辑器技术选型的历史起点 本文围绕 working group/文档前端开发工具Starlight 404 页面定制指南用 splash 模板与 hero 构建多语言错误页Starlight 404 页面定制指南用 splash 模板与 hero 构建多语言错误页 本篇技术指南以 Starlight 官方文档站中 印地语 404文档前端开发工具Iosevka 25.1.0 发布说明深度解析新增字符、字符变体覆盖扩展与风格集赋值修复Iosevka 25.1.0 发布说明深度解析新增字符、字符变体覆盖扩展与风格集赋值修复 Iosevka 是一款由代码编写的代码字体Versatile文档前端开发工具上一篇从部署到跑通 RAG 问答与知识图谱Yuxi 多租户智能体平台完整指南下一篇AutoCAD字体管家三步搞定字体缺失设计效率提升300%创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考