Jekyll 主题 Chirpy 落地实战4 类「不生效」问题的快速排查指南【免费下载链接】jekyll-theme-chirpyA minimal, responsive, and feature-rich Jekyll theme for technical writing.项目地址: https://gitcode.com/GitHub_Trending/je/jekyll-theme-chirpyChirpy 是一款极简、响应式且功能丰富的 Jekyll 主题专为技术写作设计。本文针对新手落地时最常踩的 4 类坑——文章不显示、部署后资源挂掉、语言不生效、更新时间缺失给出「症状 → 原因 → 处理」的速查路径帮你 10 分钟内定位根因。症状速查表动手改配置之前先对照下表确认你的问题属于哪一类再跳到对应章节现象常见原因排查方向新文章不在首页 / 点开 404文件名不符合YYYY-MM-DD-标题.md格式项目站漏配baseurl核对文件名、目录与_config.yml中的url/baseurl本地正常部署后样式、字体、图片全挂baseurl或url配错静态资源请求到错误路径打开 F12 看 CSS/JS 请求前缀是否正确图标、字体加载慢或加载失败默认cdn地址在所在地区不可达检查_config.yml的cdn与 _data/origin/cors.yml文章里的图片不显示文章 front matter 没声明media_subpath图片路径被拼上了 CDN 前缀在文章头部补media_subpath改了语言设置站点仍是英文lang的值与语言包文件名对不上静默回退到en对照 _data/locales/ 里的文件名「最后更新」日期缺失文章文件在 git 中的提交记录少于 2 次git log查看该文章文件的历史评论区不出现comments.provider留空即等于禁用设置 provider 并补齐对应子配置文章写了却不显示在首页点开是 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 步收敛文章文件名是YYYY-MM-DD-标题.md且确实放在_posts/里url已填完整域名项目站的baseurl以/项目名形式配了F12 中 CSS/JS/图片的请求前缀是否全部正确、返回 200默认 CDN 在你的地区是否可达必要时开assets.self_host文章内的本地图片front matter 里声明了media_subpath吗lang的值与_data/locales/中文件名逐字一致评论、目录等功能comments.provider与文章级 front matter 的开关都打开了依赖「最后更新」的文章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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考