Jekyll 排除故障（Jekyll 常见报错）

如果你在安装或使用 Jekyll 的过程中遇到问题，下面这些提示可能会对你有所帮助。如果你遇到的问题不在下方列出，请务必查看我们的其他帮助资源。

TOC
Installation Problems
Problems running Jekyll
Base-URL Problems
Configuration problems
Markup Problems
Production Problems

安装问题

如果你在安装 gem 的过程中遇到错误，可能是因为你需要为 Ruby 2.x 安装用于编译扩展模块的头文件。

在 Ubuntu 或 Debian 系统中，可以通过以下命令安装：

sudo apt-get install ruby2.6-dev

在 Red Hat、CentOS 和 Fedora 系统中，可以运行：

sudo yum install ruby-devel

在 Arch Linux 上，你需要执行：

sudo pacman -S ruby-ffi

在 Ubuntu 中，如果你在执行 bundle exec jekyll serve 后卡住，并看到类似 Could not locate Gemfile 或 .bundle/ directory 的错误信息，很可能是因为依赖项还没有全部安装完。较新的 Ubuntu 系统需要同时安装 ruby 和 ruby-all-dev：

sudo apt-get install ruby ruby-all-dev

在 NearlyFreeSpeech 上，你需要在安装 Jekyll 之前运行以下命令：

export GEM_HOME=/home/private/gems
export GEM_PATH=/home/private/gems:/usr/local/lib/ruby/gems/1.8/
export PATH=$PATH:/home/private/gems/bin
export RB_USER_INSTALL='true'

在 Gentoo 上安装 RubyGems 的方法是：

sudo emerge -av dev-ruby/rubygems

在 Windows 上，你可能需要安装 RubyInstaller DevKit。

在 Android（使用 Termux）上，你可以通过以下命令安装所有依赖：

apt update && apt install libffi-dev clang ruby-dev make

在 macOS 上，你可能需要更新 RubyGems（只有在必要时使用 sudo）：

gem update --system

如果仍然遇到问题，可以通过以下命令下载安装新的命令行工具（如 gcc）：

xcode-select --install

安装这些工具后，你就可以尝试使用以下命令来安装原生 gem（仍然建议只在必要时使用 sudo）：

gem install jekyll

请注意，升级 macOS 并不会自动升级 Xcode（需要单独在 App Store 中完成），而旧版本的 Xcode 可能会影响命令行工具的使用。如果遇到这种情况，请升级 Xcode 并重新安装更新后的命令行工具。

以非超级用户身份运行 Jekyll（无需 sudo!）

在大多数 Linux 发行版、macOS 和 Windows 上的 Bash on Ubuntu 中，可以通过在 .bashrc 文件末尾添加以下几行，作为非超级用户运行 Jekyll，并且无需将 gem 安装到系统范围的目录中：

# Ruby exports

export GEM_HOME=$HOME/gems
export PATH=$HOME/gems/bin:$PATH

这告诉 gem 将其 gem 安装到用户的主目录中，而不是系统范围的目录，并将本地的 jekyll 命令添加到用户的 PATH 中，优先于任何系统路径。

这对于许多权限受限的共享虚拟主机服务也很有用。在运行 gem install jekyll bundler 之前将这些 export 添加到 .bashrc 中，就可以完全实现无 sudo 的 Jekyll 安装。

要使新的 export 生效，可以关闭并重新打开 Bash，注销并重新登录 shell 账户，或者在当前运行的 shell 中执行 . .bashrc。

如果你在运行 jekyll new 命令时看到如下错误，可以按照上述方法解决：

jekyll new test

Running bundle install in /home/user/test...

Your user account is not allowed to install to the system RubyGems.
You can cancel this installation and run:

    bundle install --path vendor/bundle

to install the gems into ./vendor/bundle/, or you can enter your password
and install the bundled gems to RubyGems using sudo.

Password:

完成上述设置后，jekyll new 命令应该就能正常运行了。

Jekyll 与 macOS

从 macOS 10.11 版本开始引入了系统完整性保护（SIP），一些以前可写的目录现在被视为系统目录，不再开放写权限。鉴于这些变化，有几种简单的方法可以让你顺利安装运行 Jekyll。一种方法是更改 gem 的安装位置（只在必要时使用 sudo）：

gem install -n /usr/local/bin jekyll

或者，也可以安装并使用 Homebrew 来设置 Ruby，步骤如下：

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

安装 Homebrew 后，接着运行：

brew install ruby

对于有更复杂需求的高级用户，推荐使用一些 Ruby 版本管理器来安装 Jekyll，例如：RVM、rbenv、chruby 或其他等。

如果你选择使用上述方式之一安装 Ruby，可能需要使用以下命令修改你的 $PATH 变量：

export PATH=/usr/local/bin:$PATH

图形界面（GUI）应用可以通过以下方式修改 $PATH：

launchctl setenv PATH "/usr/local/bin:$PATH"

这些方法之所以推荐，是因为 /usr/local 被认为是在启用 SIP 的系统中一个“安全”的位置，能避免与 Apple 自带 Ruby 版本的冲突，并且可以将 Jekyll 及其依赖保持在一个隔离环境中。这样也带来了一个好处：当你添加或移除 gem 时无需使用 sudo。

找不到 JavaScript 运行时。（ExecJS::RuntimeUnavailable）

当你没有合适的 JavaScript 运行时，在安装 jekyll-coffeescript 时可能会出现这个错误。为了解决这个问题，可以安装 execjs 和 therubyracer 这两个 gem，或者直接安装 nodejs。更多信息请查看 issue #2327。

运行 Jekyll 时的问题

macOS

Jekyll 与 ARM64 架构的 macOS 兼容。
不过，使用旧版本的 ffi 时，执行 bundle exec jekyll serve 可能会失败。

你可能需要运行 bundle update，或手动将 ffi 更新到至少 1.14.2 版本。

Debian 或 Ubuntu

在 Debian 或 Ubuntu 上，你可能需要将 /var/lib/gems/1.8/bin/ 添加到你的路径中，
这样 jekyll 可执行文件才能在终端中正常使用。

Base-URL 问题

如果你使用了类似这样的 base-url 选项：

jekyll serve --baseurl '/blog'

……那么请确保你访问网站的地址为：

http://localhost:4000/blog/index.html

直接访问以下地址是无效的：

http://localhost:4000/blog

配置问题

冲突的配置设置的优先级顺序如下：

命令行标志
配置文件设置
默认值

也就是说：默认设置会被 _config.yml 中指定的选项覆盖，而命令行中指定的标志会覆盖所有其他地方指定的设置。

注意：从 v3.3.0 版本起，Jekyll 默认不会处理 node_modules 和 vendor 目录下的某些子目录。但是，如果在配置文件中显式定义了 exclude: 数组，则会覆盖该默认设置，导致一些用户在构建站点时遇到错误，错误信息如下：

    ERROR: YOUR SITE COULD NOT BE BUILT:
    ------------------------------------
    Invalid date '<%= Time.now.strftime('%Y-%m-%d %H:%M:%S %z') %>':
    Document 'vendor/bundle/gems/jekyll-3.4.3/lib/site_template/_posts/0000-00-00-welcome-to-jekyll.markdown.erb'
    does not have a valid date in front matter.

将 vendor/bundle 添加到 exclude: 列表中可以解决此问题，但这将导致 /vendor/ 下的其他子目录（如果有 /node_modules/ 也存在的话）被处理到目标文件夹 _site 中。

正确的解决方法是采用 exclude: 的默认设置，而不是完全覆盖它：

对于 v3.4.3 版本及以下，exclude: 设置应如下所示：

exclude:
  - Gemfile
  - Gemfile.lock
  - node_modules
  - vendor/bundle/
  - vendor/cache/
  - vendor/gems/
  - vendor/ruby/
  - any_additional_item # 用户自定义的项目放在最后

从 v3.5 版本起，Gemfile 和 Gemfile.lock 默认被排除。因此，在大多数情况下，不需要在配置文件中再次定义 exclude: 数组。所以现有的定义可以根据上述方法修改，也可以完全删除或注释掉，以便今后方便编辑。

标记问题

Jekyll 使用的各种标记引擎可能会出现一些问题。本页面将记录这些问题，以帮助其他可能遇到相同问题的用户。

Liquid

Liquid 版本 2.0 似乎破坏了模板中 {{ 的使用。与以前的版本不同，在 2.0 中使用 {{ 会触发以下错误：

'{{' was not properly terminated with regexp: /\}\}/  (Liquid::SyntaxError)

摘要

从 v1.0.0 版本开始，Jekyll 自动生成文章摘要。从 v1.1.0 版本开始，Jekyll 还会通过 Liquid 处理这些摘要，这可能会导致一些奇怪的错误，比如引用不存在或者标签没有关闭。如果遇到这些错误，尝试在 _config.yml 中设置 excerpt_separator: ""，或者将其设置为一些无效的字符串。

生产环境问题

如果你在生产环境构建时遇到静态文件无法找到的问题，从 v3.2.0 版本开始，你应该将你的环境设置为 production。这个问题是由于尝试复制一个不存在的符号链接导致的。

请报告你遇到的问题！

如果你遇到 bug，请在 GitHub 上创建一个问题，描述问题和任何你找到的解决方法，以便我们能在这里为其他人记录它。