故障排除

如果你在安装或使用 Jekyll 时遇到问题，这里有一些可能会有帮助的提示。如果你遇到的问题不在以下内容中，请查看我们的其他帮助资源。

安装问题
运行 Jekyll 时的问题
基本 URL 问题
配置问题
标记问题
生产问题

安装问题

如果你在 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.app 可能会干扰上面下载的命令行工具。如果你遇到此问题，请升级 Xcode 并安装升级后的命令行工具。

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

在大多数 Linux、macOS 和 Windows 上的 Ubuntu Bash 上，可以通过将以下行添加到 .bashrc 文件的末尾，以非超级用户身份运行 Jekyll，而无需将 gem 安装到系统范围的位置

# Ruby exports

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

这告诉 gem 将其 gem 放置在用户的 home 文件夹中，而不是系统范围的位置，并将本地 jekyll 命令添加到用户的 PATH 中，位于任何系统范围路径之前。

这对于许多共享虚拟主机服务也很有用，在这些服务中，用户帐户只有有限的权限。在运行 gem install jekyll bundler 之前，将这些导出项添加到 .bashrc 中，可以完全以非 sudo 的方式安装 Jekyll。

要激活新导出项，请关闭并重新启动 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

随着 v10.11 中系统完整性保护的引入，以前可写的几个目录现在被视为系统位置，不再可用。鉴于这些更改，有几种简单的方法可以启动并运行。一种选择是更改 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 版本管理器（RVM、rbenv、chruby、等）来安装 Jekyll 会很有帮助。

如果您选择使用上述方法之一来安装 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。请查看问题 #2327 以获取更多信息。

运行 Jekyll 时的问题

macOS

Jekyll 与采用 ARM64 架构的 macOS 兼容。但是，bundle exec jekyll serve 可能会在较旧版本的 ffi 中失败。

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

Debian 或 Ubuntu

在 Debian 或 Ubuntu 上，您可能需要将 /var/lib/gems/1.8/bin/ 添加到您的路径中，以便在终端中使用 jekyll 可执行文件。

基本 URL 问题

如果您正在使用 base-url 选项，如下所示

jekyll serve --baseurl '/blog'

… 那么请确保您访问以下网站

https://127.0.0.1:4000/blog/index.html

仅访问以下网址不起作用

https://127.0.0.1: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 # any user-specific listing goes at the end

从 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。此问题是由尝试复制不存在的符号链接引起的。

请报告您遇到的问题！

如果您遇到错误，请在 GitHub 上创建问题，描述问题以及您找到的任何解决方法，以便我们在此处为其他人记录它。