Jekyll 无扩展名 Permalink 实战：用 `/:title` 实现无后缀 URL 并避免输出陷阱-平芜编程栈

前端
CMS

【免费下载链接】jekyll

:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby

项目地址：https://gitcode.com/gh_mirrors/je/jekyll

导读

本篇文章以 Jekyll 仓库中的一篇真实测试文章 2015-02-20-extensionless-permalink.markdown 为骨架，深入讲解"无扩展名 Permalink"这一重要但常被忽视的 URL 配置主题：如何通过permalink: /:title让文章以/extensionless-permalink这样的纯路径形式呈现（URL 中不带.html、.md等后缀）。读完本文，你将掌握 Permalink 模板中:title、:output_ext等占位符的作用、无扩展名 URL 在页面与文章两种资源上的差异、以及配置后容易踩到的静态文件输出陷阱，并能参照源码级证据排查实际问题。

一、无扩展名 Permalink 是什么

在 Jekyll 中，permalink 决定了内容在生成站点中的最终 URL 形态。默认情况下，文章与页面的 URL 会带.html后缀；而"无扩展名 Permalink"指在 Front Matter 中显式声明一个不含:output_ext占位符的 permalink 模板，例如：

--- layout: ~ title: Extensionless Permalink permalink: /:title ---

这是仓库测试源文件中 2015-02-20-extensionless-permalink.markdown 的真实内容：它声明了一个无layout、标题为Extensionless Permalink、permalink 为/:title的测试文章，正文只输出{{ page.url }}，用于验证 Jekyll 对无扩展名 permalink 的解析结果。当这篇文章被构建时，它的最终 URL 将是/extensionless-permalink，而不是默认的/2015/02/20/extensionless-permalink.html。

这种 URL 形态的典型价值在于：

URL 更简洁：没有.html后缀，路径即标题，便于阅读和分享；
与 RESTful 路径风格一致：看起来像目录而非文件，利于某些场景下的 SEO 与 URL 组织；
可作为迁移/兼容场景的验证手段：测试文件中用{{ page.url }}直接输出解析结果，方便在构建产物中确认 URL 是否符合预期。

需要说明的是，无扩展名 URL 与"pretty permalink"（以/结尾、内部输出index.html）是两种不同方案：前者 URL 不带后缀，输出的是一个无扩展名文件（见下文陷阱分析）；后者 URL 以斜杠结尾，输出目录下的index.html。

二、Permalink 模板的占位符体系

理解无扩展名 permalink，首先要理解 Jekyll 的 URL 模板机制。Jekyll 通过 lib/jekyll/url.rb 中的URL类完成从模板到 URL 的生成：模板中形如:title、:categories、:year的占位符会被替换为对应资源的值，替换逻辑分别由generate_url_from_hash与generate_url_from_drop实现（见 url.rb）。

常见占位符包括：

占位符	含义	典型来源
`:title`	文章/文档标题（slug 化）	文件名的标题部分
`:categories`	分类层级	Front Matter 中的`categories`
`:year`/`:month`/`:day`	文章日期	文件名中的日期前缀
`:y_day`	一年中的第几天	日期计算
`:week`/`:short_day`	周数与星期缩写	周日期风格
`:basename`	源文件基名	页面文件
`:output_ext`	输出文件扩展名	由转换器决定，如`.html`
`:path`	相对路径	集合目录/页面目录

对于文章（Document），URL 模板的来源链路为：Document#url_template委托给所属集合的url_template（见 document.rb）；对于posts集合，默认模板由 lib/jekyll/configuration.rb 中的STYLE_TO_PERMALINK映射给出，其中:date风格为/:categories/:year/:month/:day/:title:output_ext，pretty风格为/:categories/:year/:month/:day/:title/（见 configuration.rb）。

关键点在于：默认模板的末尾带有:output_ext或以/结尾，而permalink: /:title两者皆无——末尾是纯占位符:title，因此生成的 URL 不带任何扩展名。

三、Front Matter 中的 permalink 优先级与写法

在文章或页面的 Front Matter 中直接写permalink时，它的优先级高于站点全局的permalink配置（如_config.yml中的permalink: pretty）。这一点在测试中也有印证：例如 test_configuration.rb 验证了当用户显式设置collections.posts.permalink时，默认值会被保留不动，即显式声明优先。

写法上注意两点：

必须以/开头：permalink: /:title而非permalink: :title。URL 类的sanitize_url方法（见 url.rb）会强制在结果前补/并压缩连续斜杠，但规范写法仍是显式带上前导斜杠；
不要混入:output_ext：一旦模板中出现:output_ext，URL 就会带上.html后缀，不再是"无扩展名"形态。若需要扩展名，可显式写permalink: /:title:output_ext。

另外，站点级也可以配置全局无扩展名风格。permalink_style若被设置为不带斜杠与后缀的模板（如/:title），所有页面与文章都会按该模板生成 URL。仓库测试 test_page.rb 专门验证了@site.permalink_style = "/:title"时，contacts.html的 URL 为/contacts。

四、验证无扩展名 URL 的生成结果

测试源文章在正文中输出{{ page.url }}，构建后该输出即为/extensionless-permalink。这与仓库测试中的断言一致：

test_page.rb：permalink_style = "/:title"时page.url == "/contacts"；
test_page_without_a_file.rb：permalink_style = :title时properties.html生成page.url == "/properties"；
test_utils.rb：Utils.add_permalink_suffix("/:basename", "/:title")返回"/:basename"，确认无后缀模板不会被追加扩展名。

URL 生成的核心路径在 lib/jekyll/url.rb：URL#to_s优先使用generated_permalink（即 Front Matter 中显式声明的 permalink），其次才回退到generated_url（基于模板）。因此permalink: /:title会直接生成/extensionless-permalink。

五、无扩展名 permalink 的输出陷阱：静态文件覆盖

这是无扩展名 permalink 最容易踩的坑，也是仓库中该测试文章的真实意图之一——验证无扩展名 URL 与源文件同名静态文件的冲突处理。

从源码看，Page 与 Document 的destination逻辑（见 page.rb 与 document.rb）为：

path = site.in_dest_dir(dest, URL.unescape_path(url)) path = File.join(path, "index") if url.end_with?("/") path << output_ext unless path.end_with? output_ext

当 URL 为/extensionless-permalink（不以/结尾、无扩展名）时，output_ext（对文章而言通常是.html）会被追加，最终输出文件其实是_site/extensionless-permalink.html，而不是无扩展名文件。也就是说：

URL 是/extensionless-permalink，但磁盘上输出的是extensionless-permalink.html；
若恰好存在同名源文件extensionless-permalink.html，两者输出会指向同一个目标文件，可能出现覆盖或顺序相关的构建问题；
对于无扩展名 URL，Web 服务器通常按 Content-Type 推断或由服务器配置决定如何提供该路径下的资源，需配合服务器 rewrite/扩展名映射才能优雅呈现。

仓库中还有一类"无扩展名静态文件"的用例可作佐证：静态文件（如集合_methods下的extensionless_static_file）在 lib/jekyll/static_file.rb 中其output_ext被显式置空、title为空字符串，测试 test_site.rb 验证此类文件会被纳入site.static_files输出。这说明 Jekyll 内部对"无扩展名"资源与"文章/页面资源"的处理路径不同：前者原样拷贝无后缀文件，后者才会追加output_ext。因此，当你在文章上配置无扩展名 permalink 时，实际生成的仍可能是带.html后缀的物理文件，只是 URL 更干净。

六、实操：在真实站点中配置无扩展名 permalink

方式一：单篇文章/页面级配置

在目标文章的 Front Matter 中添加：

--- title: My Post permalink: /:title ---

构建后文章 URL 为/my-post。

方式二：站点级全局配置

在_config.yml中设置：

permalink: /:title

或使用内置风格名（如pretty、date、ordinal、weekdate、none），完整映射见 configuration.rb。注意站点级配置会影响所有页面与文章，page.rb#template（见 page.rb）中非 HTML 文件（如sitemap.xml）会固定使用/:path/:basename:output_ext模板，不会被无扩展名风格影响。

验证方式

运行bundle exec jekyll build；
检查_site目录：若 URL 为/extensionless-permalink，物理文件通常是_site/extensionless-permalink.html；
在源码中使用{{ page.url }}输出 URL（正如测试文章所做），或使用site.posts遍历检查生成结果。

七、适用前提与注意事项

无扩展名 URL 依赖服务器配置：静态服务器需能正确识别该路径并提供extensionless-permalink.html的内容（如 Nginx/Apache 的try_files、扩展名映射或 rewrite）。若服务器按扩展名决定 MIME 类型，无扩展名路径可能返回错误 Content-Type；
注意同名文件冲突：避免源目录中同时存在extensionless-permalink.markdown（声明无扩展名 permalink）与extensionless-permalink.html，否则输出目标重叠，构建结果不确定；
文章与页面行为不同：文章/页面会追加output_ext生成物理文件（URL 无后缀），而真正的无扩展名静态文件（static_file.rb中output_ext为空）会原样拷贝为无后缀文件——两者不要混为一谈；
测试文件本身仅用于验证：2015-02-20-extensionless-permalink.markdown是仓库test/source下的测试源文件，不参与正式站点内容，其layout: ~与{{ page.url }}均为验证而设，实际站点中请按需填写布局。

结语

无扩展名 permalink 是 Jekyll URL 定制中简洁而实用的一环：通过permalink: /:title即可让文章 URL 不带后缀。但"URL 无后缀"并不等于"输出无后缀文件"，理解 url.rb 的模板替换与destination的扩展名追加逻辑，才能避开同名覆盖与服务器 MIME 识别等实际问题。对照仓库中的测试源文章、test_page.rb 与 configuration.rb 等证据，你可以自行复现并验证这一行为。