Ghost 主题路由配置完全指南读懂与使用routes.yamlcontent/settings【免费下载链接】GhostIndependent technology for modern publishing, memberships, subscriptions and newsletters.项目地址: https://gitcode.com/GitHub_Trending/gh/Ghost导读routes.yaml是 Ghost 博客平台中决定站点 URL 结构与路由映射的核心配置文件它决定了首页聚合哪些文章、每篇文章使用什么链接格式、标签与作者归档页挂在哪个路径之下。本文以 Ghost 仓库中 ghost/core/content/settings/README.md 为主体结合其源码级实现路由设置解析器、存储适配器与动态路由服务为你完整拆解默认配置文件的三个组成块routes、collections、taxonomies讲清楚每个键的含义、可扩展的进阶选项以及如何安全地修改并让改动生效。配置文件在哪content/settings/routes.yaml在标准的 Ghost 安装目录中路由设置文件位于content/settings/routes.yaml。仓库中对应的存放位置与说明文档为 ghost/core/content/settings/README.md其当前仅收录了一个README.md因为真正生效的routes.yaml属于运行期数据——首次发布内容时才会由系统生成到本地磁盘。从源码看文件读写由文件型存储适配器完成FileStore.ts 中以常量YAML_FILENAME routes.yaml定义了文件名并指向content/settings目录作为basePath。它会在文件不存在时自动回落读取打包的内置默认值 default-routes.yaml这意味着即使你从未手工创建过routes.yamlGhost 也会用内置默认路由启动真正的文件只在第一次保存修改后才落地磁盘。Ghost 还支持把routes.yaml托管到 S3 之类的远程存储见 S3RouteSettingsStore.ts实现多实例间共享同一份路由配置。默认配置逐段精读README 中展示的默认routes.yaml全文如下与仓库内置默认 default-routes.yaml 完全一致routes: collections: /: permalink: /{slug}/ template: - index taxonomies: tag: /tag/{slug}/ author: /author/{slug}/顶层结构三段式routes / collections / taxonomies文件由三个顶层键构成缺一不可但都允许留空。这一结构在解析层被定义为固定的三段式 schema见 route-settings-parser.tsconst RouteSettingsSchema z.object({ routes: z.record(z.string(), z.unknown()).nullable().optional().default({}), collections: z.record(z.string(), z.unknown()).nullable().optional().default({}), taxonomies: z.record(z.string(), z.string()).nullable().optional().default({}), });顶层键用途默认配置中的内容routes自定义静态路由如/about/独立页面、RSS 等附加路由可挂载模板或 channel 控制器空collections内容聚合路由决定某路径下展示哪些文章及其 permalink 格式根路径/permalink 为/{slug}/模板indextaxonomies分类归档路由为 tag 与 author 定义 URL 模式/tag/{slug}/与/author/{slug}/collections文章的聚合与 URL 生成器collections 是配置中信息量最大的部分。默认配置只保留一个根集合/它会聚合站点全部文章并让每一篇公开发布的文章获得https://你的域名/{slug}/这样的永久链接。各字段含义如下/collection 路径作为顶层键的 key表示这个集合挂在站点的哪个 URL 前缀下必须以/开头和结尾。permalink集合内文章生成 URL 的模板。{slug}是动态占位符在渲染时被替换为文章 slug。因此permalink: /{slug}/意味着文章“hello-world”的最终链接为/hello-world/。template渲染该集合列表页使用的主题模板名。默认值为index即主题的index.hbs。它接受单个字符串或字符串数组数组用于按顺序做模板回退见 route-settings-parser.ts 中TemplateField的归一化逻辑。taxonomies标签与作者的归档 URLtaxonomies定义 Ghost 的两类分类归档——tag标签与author作者。在解析器中任何非tag/author的键都会被直接判为非法见 route-settings-parser.tsif (![tag, author].includes(key)) { throw validationError(..., Unknown taxonomy. Please use tag or author., ...); }注意这里使用的是{slug}占位符写法与 permalink 的约束一致。源码对路径合法性有统一校验validatePath几条硬性规则是必须以/开头、以/结尾只能使用{param}占位符语法不能用 Express 风格的:param——若写成/tag/:slug/解析器会报错并提示改为/tag/{slug}/。进阶让routes.yaml支撑更多站点形态默认配置是最小可用集合。源码解析器route-settings-parser.ts实际支持的字段远不止 README 展示的这些下面是经过源码验证的完整能力矩阵。routes区块静态页面与 channelroutes下的每条记录把一个 URL 路径映射到一个模板或一个带controller: channel的列表控制器。合法的 route 值有两种形态简写形态——直接写模板名routes: /about/: template: aboutchannel 形态——把路径变成一个可筛选的文章流路由对象 schema 见 route-settings-parser.tsroutes: /featured/: controller: channel template: - featured filter: featured:true order: published_at desc limit: 10 rss: true此时支持controller: channel、template、filter、order、limit、rss及data等可选键。默认的routes:之所以留空是因为 Ghost 的主题层如/featured/、分页 URL由路由控制器的默认机制补全。collections的可选键collection 除了permalink与template还可叠加以下过滤与排序能力collection schema 见 route-settings-parser.ts键类型作用示例filterstringNQL 过滤器决定哪些文章进入该集合filter: tag:photoorderstring排序表达式order: published_at desclimitnumber /all每页条数上限limit: 5rssboolean是否为此集合开启 RSSrss: truedata见下文为集合页面注入额外数据data: tag.recipes例如用filter实现“仅聚合某一标签文章”的独立博客集合collections: /blog/: permalink: /blog/{slug}/ template: blog filter: tag:blogdata路由级数据注入与两个保留命名空间data可以把一个具名资源直接“喂”给特定模板比如在首页渲染“特色标签”。它支持两种写法底层模型见 base.ts简写形态resource.slug资源必须是tag、page、post、authorcollections: /: permalink: /{slug}/ template: index data: featured_post: post.hello-world recipes_tag: tag.recipes其中recipes_tag这样自定义的 key 会暴露给模板使用。但解析器保留了若干禁止用作自定义 key 的名字RESERVED_DATA_KEYS见 route-settings-parser.tsresource、type、limit、order、include、filter、status、visibility、slug、redirect另外author因历史原因也被单独保留并建议更换名字。长格式——用 map 描述一个具名数据条目需声明type与resourceroutes: /resources/tag/recipes/: template: tag-recipes data: tag: type: read resource: tags slug: recipestype只能取read读取单条需配slug或browse按filter/limit等批量读取见 route-settings-parser.ts。长格式下resource使用复数集合名tags、posts、pages、authors。修改配置的正确姿势三种生效途径途径一直接编辑文件后重启在content/settings/routes.yaml中改好后重启 Ghost。每次启动时动态路由服务会把路由设置载入前端 RouterManager见 dynamic-routing-service.js 的start()流程它由 boot.js 中的initDynamicRouting在每次启动时调用。途径二通过管理后台下载 / 上传在 Ghost Admin 的Settings → Advanced → Routes中可直接编辑并保存routes.yaml。上传链路dynamic-routing-service.js的执行顺序是解析并校验上传内容——非法文件在落盘前就被拒绝ROUTE_SETTINGS_VALIDATION_ERROR通过store.replace()原子写盘旧文件自动生成带时间戳的备份见 FileStore.ts触发bridge.reloadFrontend()前端路由热重载无需重启进程。途径三API 接口Admin API 暴露了路由设置的下载与上传端点入口见 settings.js便于自动化部署流程把routes.yaml作为代码资产管理。校验规则与常见报错配置文件解析使用 js-yaml 读取 YAML再用 zod schema 校验route-settings-parser.ts。较常见的错误及原因Missing leading slash/Missing trailing slash所有路径route 路径、collection 路径、permalink、taxonomy permalink必须以/开头并结尾。uses the :param notation路径中混入了 Express 风格:slug应改写为 Ghost 的{slug}。Unknown taxonomytaxonomies 区块只允许tag和author。Please define a permalink routecollection 缺少permalink见校验 route-settings-parser.ts。Please define a template某个 route 既没写模板、又没有data/content_type兜底。author is reserveddata区块用author作自定义键。当routes.yaml非法且无法加载时Ghost 会记录一条明确的ROUTE_SETTINGS_VALIDATION_ERROR日志并向上抛出真实错误提示你修复文件dynamic-routing-service.js而不是默默降级运行。路由系统全貌配置文件如何变成站点 URLroutes.yaml只是起点配置解析后的路由模型Route/CollectionConfig/TaxonomyConfig定义见 base.ts会被前端路由系统消费链路分布在以下模块中路由模型与存储抽象route-settings-base 包定义了RouteSettingsStoreBase及get()/replace()接口是本地磁盘FileStore.ts与 S3S3RouteSettingsStore.ts两种实现的共同契约。前端路由注册配置解析产物交给 RouterManager按类型创建 collection / taxonomy / static 等路由器并挂载到父路由相关文件见 routing/index.js、router-manager.js。URL 服务后台 URL 服务会基于这些路由构建站点所有内容 URL即使不对外提供页面服务后台任务也需要加载路由见 url/config.js 与 lazy-url-service.ts。因此在 Ghost 中“改 URL 结构”从来不是只影响链接显示而是牵动整条从路由注册、内容分页到站点地图与 RSS 的链路而这一切都以routes.yaml为唯一事实来源。小结content/settings/routes.yaml是一份“短小但系统级”的配置三段结构分别治理静态路由、文章聚合与分类归档占位符一律使用{slug}修改后可经文件重启、Admin 上传热加载或 Admin API 三种方式生效。理解它就等于掌握了自定义 Ghost 博客 URL 架构的钥匙——无论是想改 permalink 格式、拆出按标签隔离的二级博客还是为自定义页面注入路由级数据都可以从这份 YAML 开始再回到源码中的 schema 校验确认每个字段的合法取值与边界。【免费下载链接】GhostIndependent technology for modern publishing, memberships, subscriptions and newsletters.项目地址: https://gitcode.com/GitHub_Trending/gh/Ghost创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考