疑難排解

如果您在安裝或使用 Jekyll 時遇到問題，以下提供一些可能有助益的提示。如果您遇到的問題未在下方說明，請查看我們的其他說明資源。

安裝問題
執行 Jekyll 的問題
基本網址問題
設定問題
標記問題
製作問題

安裝問題

如果您在 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 後卡住，並看到類似 找不到 Gemfile 或 .bundle/ 目錄 的錯誤訊息，這可能是因為尚未完全滿足所有需求。最近的 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 放置在使用者的家目錄中，而不是系統範圍的位置，並將本機 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 中系統完整性防護的導入，幾個以前可寫入的目錄現在被視為系統位置，不再可用。有了這些變更，有幾種簡單的方法可以開始執行。一個選項是變更寶石將安裝的位置（同樣，僅在必要時使用 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 及其相依性保留在沙盒環境中。這也具有不需要在您想要新增或移除寶石時使用 sudo 的額外好處。

找不到 JavaScript 執行環境。(ExecJS::RuntimeUnavailable)

當您沒有適當的 JavaScript 執行時間時，安裝 jekyll-coffeescript 時可能會發生此錯誤。要解決此問題，請安裝 execjs 和 therubyracer 程式庫，或安裝 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 可執行檔。

基本網址問題

如果您使用類似下列的 base-url 選項

jekyll serve --baseurl '/blog'

… 然後請確定您在

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

中存取網站。只存取

https://#: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 上建立一個問題，描述問題以及您找到的任何解決方法，以便我們可以將其記錄在這裡供其他人參考。