企业官网建设流程全解析

Jekyll 主题 Chirpy 落地实战：4 类「不生效」问题的快速排查指南

【免费下载链接】jekyll-theme-chirpyA minimal, responsive, and feature-rich Jekyll theme for technical writing.项目地址: https://gitcode.com/GitHub_Trending/je/jekyll-theme-chirpy

Chirpy 是一款极简、响应式且功能丰富的 Jekyll 主题，专为技术写作设计。本文针对新手落地时最常踩的 4 类坑——文章不显示、部署后资源挂掉、语言不生效、更新时间缺失，给出「症状 → 原因 → 处理」的速查路径，帮你 10 分钟内定位根因。

症状速查表

动手改配置之前，先对照下表确认你的问题属于哪一类，再跳到对应章节：

文章写了却不显示在首页，点开是 404

现象：bundle exec jekyll serve编译毫无报错，首页却找不到你刚写的文章；直接访问它的链接返回 404。

根因：多半是这两件事之一。一是 Jekyll 只认_posts/目录中形如2019-08-08-write-a-new-post.md的文件，日期格式错一位、或者文件放在别的目录，都会被静默忽略（仓库里 _posts/ 下的示例文章可以直接当格式参照）；二是你部署的是「项目站」（访问地址形如用户名.github.io/项目名），这类站点必须设置baseurl，否则所有链接都指向根路径，而实际资源在/项目名/子路径下。

处理：先修正文件名与目录位置，再在 _config.yml 中补上：

baseurl: "/project-name"

项目站漏配它是首页 404 的头号原因，值必须以/开头且不带末尾斜杠。

如果改完首页能看到文章且链接以/posts/文章标题/开头，说明已修复；仍不对就转下一节，多半是url也错了。

本地预览正常，部署后样式、字体、图片全挂

现象：本地 127.0.0.1 打开一切正常，推到线上后页面变回「裸 HTML」，F12 里 CSS、JS、图标一片 404，或者能加载但慢得像幻灯片。

根因：先分清「挂掉」还是「变慢」。挂掉几乎都出在路径：Chirpy 用url生成绝对链接，url留空或写错会让分享、RSS 等链接全部失效；baseurl漏配则让静态资源请求打到错误前缀。变慢则多半因为主题默认cdn: "https://chirpy-img.netlify.app"，这是一个海外 CDN，在部分地区访问极慢，而图标、字体等静态资源清单定义在 _data/origin/cors.yml，全部走这个前缀。

处理：把两项写全：

url: "https://username.github.io" baseurl: "/project-name"

第一条必填，第二条项目站必填。若你的地区访问默认 CDN 困难，把cdn换成可达地址；更彻底的做法是开启自托管静态资源：

assets: self_host: enabled: true

主题内置了这套切换机制，开启后资源地址会改用本地路径，不再依赖外部 CDN。改完硬刷新页面，F12 中所有请求路径都应以你的域名 + 正确前缀开头且返回 200，即算通过。

改了语言设置，站点还是英文

现象：明明在 _config.yml 里改了lang，界面按钮、分类、归档文案却原封不动停在英文。

根因：主题只在你填的值与 _data/locales/ 目录下的语言包文件名一致时才切换界面语言，对不上就静默回退到默认值en——不会报错、不提示。最常见的错误是图省事写zh或ZH，而实际文件名是zh-CN.yml、zh-TW.yml。

处理：对照 locales 目录里的文件名（去掉.yml后缀）原样填写：

lang: zh-CN

值必须与文件名逐字一致，包括连字符和大小写。刷新后如果「搜索」「标签」等文案变成中文即生效；若仍是英文，只剩一种可能——值又和文件名对不上了，回目录再核对一遍。

文章页「最后更新」日期不显示

现象：文章头部有发布日期，「最后更新」一栏却始终空白，明明改过内容。

根因：这个功能由 _plugins/posts-lastmod-hook.rb 实现，构建时它会用git log读取文章文件的最后一次提交时间。注意它有两个硬前提：项目本身必须是一个 git 仓库，且这篇文章文件要有 2 次以上的提交记录。新建仓库里的文章往往只有一次提交，自然拿不到「修改时间」。

处理：先确认这条命令的输出：

git log --oneline -- "_posts/你的文章.md"

若只有一行记录，对文章做一次小改动并 commit 即可。如果历史已有多次提交却仍不显示，检查项目的_plugins/目录是否缺失了posts-lastmod-hook.rb这个文件。commit 后重新构建，文章页出现「最后更新」即修复完成。

自查清单

按顺序逐项过一遍，绝大多数「不生效」都能在第 2、3 步收敛：

1. 文章文件名是YYYY-MM-DD-标题.md，且确实放在_posts/里？
2. url已填完整域名？项目站的baseurl以/项目名形式配了？
3. F12 中 CSS/JS/图片的请求前缀是否全部正确、返回 200？默认 CDN 在你的地区是否可达，必要时开assets.self_host？
4. 文章内的本地图片，front matter 里声明了media_subpath吗？
5. lang的值与_data/locales/中文件名逐字一致？
6. 评论、目录等功能：comments.provider与文章级 front matter 的开关都打开了？
7. 依赖「最后更新」的文章，git 历史是否满足 ≥2 次提交，且_plugins/posts-lastmod-hook.rb存在？

进一步阅读

想系统过一遍安装、配置与部署流程，可阅读仓库内置的入门文章 _posts/2019-08-09-getting-started.md，配置项全貌见 _config.yml，语言包与静态资源清单分别在 _data/locales/ 和 _data/origin/cors.yml。

【免费下载链接】jekyll-theme-chirpyA minimal, responsive, and feature-rich Jekyll theme for technical writing.项目地址: https://gitcode.com/GitHub_Trending/je/jekyll-theme-chirpy