Troubleshooting( Jekyll )

解翰采

2023-12-01

如果您在安装或使用Jekyll时遇到问题，这里有一些小贴士可能会有所帮助。如果您遇到的问题没有在下面介绍，请查看 check out our other help resources 。

安装问题

如果您在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 (with 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, 以及 Bash on Ubuntu on Windows 上，可以以非超级用户身份运行Jekyll，且不必把 gems 安装到系统范围的位置，通过在 .bashrc 文件的末尾添加以下行即可实现：

# Ruby exports

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

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

这对于许多共享网络托管服务也很有用，因为用户帐户只有有限的权限。在运行 gem install jekyll bundler 之前，将这些 exports 添加到 .bashrc 中，将允许jekyll的完全 non-sudo 安装。

要激活新的 exports ，请关闭并重新启动 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 apps 可以像下面这样修改 $PATH

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

这几种方法都很有用，因为在启用了 SIP 的系统上，/usr/local 被认为是一个“安全”的位置，它们避免了与苹果公司提供的Ruby版本的潜在冲突，并且它将Jekyll及其依赖项保持在沙盒环境中。这还有一个额外的好处，即当您想要添加或删除 gem 时，不需要sudo 。

Could not find a JavaScript runtime. (ExecJS::RuntimeUnavailable)

当您没有合适的 JavaScript 运行时库时，在安装 jekyll-coffeescript 的过程中可能会出现此错误。要解决这个问题，可以安装 execjs 和 therubyracer gems ，也可以安装 nodejs。查看 issue #2327 ，了解更多信息。

运行Jekyll时出现的问题

macOS

Jekyll与具有ARM64体系结构的macOS兼容。然而，bundle exec jekyll serve 可能会 fail with older version ffi 。

您可能需要运行 bundle update 或手动把 ffi 更新到不低于 1.14.2 。

Debian or Ubuntu

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

Base-URL 的一些问题

如果您正在使用 base-url 的选项，像这样：

jekyll serve --baseurl '/blog'

… 然后请确保您访问网站的位置是这个：

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

仅访问这个是不行的：

http://localhost:4000/blog

配置上的一些问题

冲突 configuration settings 的优先顺序如下：

Command-line flags
Configuration file settings
Defaults

也就是说：defaults 被 _config.yml 中指定的选项覆盖，在命令行中指定的 flags 将覆盖其他地方指定的所有其他设置。

注意：从v3.3.0开始，Jekyll默认情况下不处理 vendor 内的 node_modules 和某些子目录。但是，通过在配置文件中显式定义exclude: array 来覆盖此默认设置，这会导致一些用户在构建站点时遇到错误，并显示以下错误消息：

    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: array 。因此，现有的定义可以按如上所述进行修改，也可以完全删除，或者注释掉，以便于将来进行编辑。

Markup Problems

Jekyll 使用的各种 markup 引擎可能存在一些问题。本页将记录它们，以帮助其他可能遇到同样问题的人。

Liquid

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

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

Excerpts

自 v1.0.0 以来，Jekyll已经自动生成了文章摘录。自 v1.1.0 版本以来，Jekyll 还通过 Liquid 传递这些摘录，这可能会在不存在引用或 tag 未关闭的情况下导致奇怪的错误。如果遇到这些错误，请尝试在 _config.yml 中设置 excerpt_separator: ""，或者将其设置为一些无意义的字符串。

生产环境中的问题

如果在 v3.2.0 之后的构建过程中遇到在生产环境中找不到静态文件的问题，您应当设置您的 environment to production 。该问题是由于试图复制不存在的符号链接而引起的。

请报告您遇到的问题！

如果你遇到一个bug，请在GitHub上 create an issue，描述这个问题和你找到的任何解决方法，这样我们就可以在这里为其他人记录它。

返回目录