开发随笔

旧版 Jekyll 博客维护笔记：Ruby 3.4 缺失默认库与未来日期过滤

归档旧版 Jekyll 博客在升级 Ruby 3.4 后缺少 csv/logger/base64 标准库，以及时区偏移缺失导致文章被当作未来日期跳过的问题。

在把博客迁移到 Jaspr 之前，维护旧版 Jekyll 仓库时遇到过两处典型的本地预览环境问题，合并归档在此备查。

1. Ruby 3.3 升级至 3.4.0 后报 LoadError

将本机 Ruby 升级到 3.4.0 后，在 Jekyll 目录执行 bundle exec jekyll s 会直接抛出 LoadError：

LoadError: cannot load such file -- csv
LoadError: cannot load such file -- logger
LoadError: cannot load such file -- base64

原因：csv、logger 与 base64 在 Ruby 3.3 及更早版本中属于随解释器自带的 default gems，旧版 Jekyll 及其插件直接 require 时并未在 gemspec 中显式声明。自 Ruby 3.4.0 起，官方将这几个库移出默认集、改为需独立安装的 bundled gems；使用 bundle exec 隔离环境启动时，未写入 Gemfile 就无法加载。

处理方式：在项目根目录的 Gemfile 中补齐声明后执行 bundle install 即可：

gem "csv"
gem "logger"
gem "base64"

2. 新建文章提示 has a future date 被跳过渲染

新建 _posts/YYYY-MM-DD-xxx.md 并启动本地预览后，页面列表里没有出现新文章，终端日志提示：

Skipping: _posts/2025-03-03-....md has a future date

原因：Jekyll 默认把声明时间晚于当前构建时刻的文章当作定时待发布内容过滤。如果 Front Matter 里只写了 date: 2025-03-03 12:00:00 而漏写东八区偏移 +0800，或者刚过零点新建当日文件、本机时钟略慢，按默认时区（常为 UTC）换算后就会落在当前时刻之后。

处理方式：

  1. 在 Front Matter 中写全带时区偏移的时间戳（如 date: 2025-03-03 00:05:00 +0800），让本地与 GitHub Pages 远端构建解析一致；
  2. 本地临时预览时加上 --future 参数：bundle exec jekyll s --future；
  3. 若不需要定时发布机制，直接在 _config.yml 中设置 future: true。