在 Windows 上运行 Jekyll

虽然官方不支持 Windows,但是可以安装一些组件实现在 Windows 上运行 Jekyll。

安装 Ruby 和 Jekyll

通过 RubyInstaller 安装

使用 RubyInstaller 在Windows系统上安装 Ruby 和 Jekyll 非常简单和便捷。

RubyInstaller 是基于 Windows 开发的 Ruby 安装程序,可以完成 Ruby、相关执行环境和相关重要组件的安装。

这里主要介绍 RubyInstaller-2.4 以及更高版本的安装,旧版本需要手动安装 Devkit

  1. 下载 RubyInstaller,选择 Ruby+Devkit 版本,并使用默认选项进行安装。
  2. 在安装向导选择 MSYS2 and MINGW development tool chain 选项,然后在最后阶段运行 ridk install 步骤,安装 gem 扩展(必须)。你可以在 RubyInstaller 文档 查看相关内容。
  3. 从“开始”菜单打开一个新的终端窗口(命令提示符窗口、cmd),为了让 PATH 环境变量生效,执行以下命令安装 Jekyll 和 Bundler:gem install jekyll bundler
  4. 检查 Jekyll 是否正确安装,通过终端执行命令: jekyll -v

如果检查 Jekyll 是否正常安装时报错,你可以重启电脑并再次通过终端运行 jekyll -v 命令。
如果仍旧报错,请去 Github 上提交问题:RubyInstaller issue

安装 Jekyll 就是如此简单,你可以开始使用 Jekll 了。

在 Windows 10 上通过 Bash 安装(Linux 子系统)

如果你使用的 Windows 10 版本是 1607 或者更高的版本,可以选择使用 WSL 在 Windows 上安裝 Linux系统,然后通过 Linux 子系统运行 Jekyll。

你必须启用 Windows 中的 Linux 子系统: Windows Subsystem for Linux

确保你电脑所有的 packages 和 repositories(软件包和储存库)都是最新版本。打开新的终端或 PowerShell 窗口,输入 bash 命令。

你的终端当前应该是 Bash,执行以下命令更新 packages 和 repository 列表(软件包和储存库列表:

sudo apt-get update -y && sudo apt-get upgrade -y

然后,安装 Ruby。可以使用 BrightBox 的储存库,它托管了 基于 Ubuntu 的 Ruby 优化版本。

sudo apt-add-repository ppa:brightbox/ruby-ng
sudo apt-get update
sudo apt-get install ruby2.5 ruby2.5-dev build-essential dh-autoreconf

然后,更新你的 Ruby gems:

gem update

安装 Jekyll:

gem install jekyll bundler

注意 更新 gem 和安装 Jekyll 的时候没有 sudo

检查你的 Jekyll 版本:

jekyll -v

这样就已经完成了在 Windows 通过 Linux 子系统安装 Jekyll 的流程,你可以开始使用 Jekll 了。

你可以检查 _posts 文件夹确保 Jekyll 正常工作,你可以看到里面有一个包含当前日期文件名的 Markdown 文件(.md)

非超级用户的问题

如果使用jekyll new命令出现“Your user account isn't allowed to install to the system RubyGems”(不允许你的用户帐户安装系统 RubyGems)的错误,请查看排除故障 Troubleshooting中的“通过非超级用户(超级管理员)身份运行 Jekyll”(Running Jekyll as Non-Superuser)。

基于 Windows 的 Ubuntu Bash 仍处于开发阶段,所以可能会有问题。

编码 Encoding

使用 UTF-8 编码,如果文件头包含 BOM 字符会导致 Jekyll 中断。所以请删除文件头的 BOM 。

然后,可以将终端代码页改为 UTF-8,可避免出现 Liquid Exception: Incompatible character encoding 报错,执行以下命令:

chcp 65001

Time Zone Management

因为 Windows 没有原生的 zoneinfo 数据源,所以 Ruby 解释器无法识别 IANA 时区。以致使用 TZ 环境变量会默认识别为 UTC/GMT 00:00。

虽然 Windows 用户可以通过 key 定义博客的时区,使用定义时区的 POSIX 格式,但是时钟更改为 DST 规则并不友好。

现在 Jekyll 使用 rubygem,通过 IANA 时区数据库 IANA Timezone Database 配置时区。 . 虽然 Jekyll v3.4 和更高版本使用 new 新建博客会默认在 Gemfile 文件中添加以下内容,但是旧的站点必须更新 Gemfile 和已安装的 gem 才能在 Windows 上正常运行:

# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
# and associated library.
platforms :mingw, :x64_mingw, :mswin, :jruby do
  gem "tzinfo", ">= 1", "< 3"
  gem "tzinfo-data"
end

自动生成网站

运行 Jekyll 后,每次修改文件后都会自动生成生成最新的站点,让每一次修改都可以实时查看。

Jekyll 使用 listen gem 监听你对文件的修改,可以在运行和构建网站(build or serve)时添 --watch 参数。

UNIX 系统内置 listen 但是 Windows 并没有这东西,所以在 Windows 系统运行 Jekyll 要额外安装指定的 gem 才能兼容 listen。

如果你 Windows 上自动生成网站遇到问题,请将以下内容添加到你站点根目录的 Gemfile 文件中:

gem "wdm", "~> 0.1.1", :install_if => Gem.win_platform?

你必须使用 Ruby+Devkit 版本的安装包安装 Ruby,并通过打开 ridk install 引导文件安装 MSYS2 构建工具,才能安装 wdm gem。