用 Netlify 发布 Jekyll 之踩坑

C. Qiu 于 2025-02-11 发布

如题，使用 Netlify 自动拉取仓库中的 Jekyll 博客源码进行发布，记录遇到的问题。

坑一：master还是main

GitHub 近年来将新的仓库默认主分支从 master 改为了 main。我本地初始化时还是 master，推送到 GitHub 后，又想统一为 main。

此处仅需简单折腾一下：

  1. 本地重命名：git branch -m master main (将本地的 master 重命名为 main)
  2. 推送新分支：git push -u origin main (将本地的 main 分支推送到远程并建立跟踪)
  3. GitHub 网站设置：在 GitHub 仓库的 Settings -> Branches 中，将 Default branch 修改为 main。
  4. 删除远程旧分支：git push origin --delete master
  5. Netlify 检查：确保 Netlify 部署设置中的分支也更新为了 main。

坑二：Netlify 构建报错bundle exec jekyll build

最折磨的环节，幸好 Netlify 的部署日志自带 AI 分析。

报错信息：

  Error message
  Command failed with exit code 1: bundle exec jekyll build
  ...
  Error mentions missing dependencies logger and csv in the Gemfile.
  # Netlify 自带的 AI 告诉我的，这个整得挺好

原因分析： Netlify 用了较新的 Ruby 版本，乍一看应该是 3.4，它要求一些以前默认包含的 gem在 Gemfile 中显式声明。我的本地环境估计因为 Ruby 版本较老就没有这个问题，毕竟我抄的这个主题发布很多年了。

解决方法：

  1. 编辑 Gemfile： 在项目根目录的 Gemfile 文件中添加缺失的 gem： 
      gem "logger"
  gem "csv"
  gem "base64"
  gem "bigdecimal"
  2. 更新 Gemfile.lock： 在主目录下运行 bundle install。它会根据 Gemfile 的改动更新 Gemfile.lock，确保依赖版本一致。
  3. 提交更改： 
      git add Gemfile Gemfile.lock
  git commit -m "Update Gemfile for Netlify build"
  git push origin main

    Netlify 会自动拉取最新代码并重新构建。

其实也可以在项目根目录添加一个 .ruby-version 文件，内容希望使用的 Ruby 版本号（如2.7.2），并提交到仓库。Netlify 会读取这个文件来确定构建时使用的 Ruby 版本。

坑三：bundle install 慢得要命

在本地执行 bundle install 时等待时间很长。

原因： bundle install默认从https://rubygems.org/下载 gem 包，因为众所周知的原因，国内访问速度十分感人。

解决方法：更换 RubyGems 源为国内镜像源。

在项目目录下执行：

bundle config mirror.https://rubygems.org https://gems.ruby-china.com
#或者使用其他国内镜像，如清华大学源

这会在项目内生成一个 .bundle/config 文件，只对当前项目生效。

或者，也可以直接改动 Gemfile 中的第一行：

source "https://rubygems.org"
#改为
source "https://gems.ruby-china.com"

然后再次运行 bundle install，速度飞起。

git 也有相似问题，push 到远程仓库 push 不动。不过这个需要一点科学上网技巧。具体操作如下：

git config --global http.proxy http://127.0.0.1:10809
git config --global https.proxy http://127.0.0.1:10809

懂的都懂，不谈嘛。

最终 Gemfile

Netlify 报错是每加一个 Gem 就报一个新的，最后总共加了logger,csv,base64和bigdecimal四行，如果图省事想用 Netlify 还不指定版本，可以参考我的 Gemfile 一次全加上：

source "https://gems.ruby-china.com"

gem "jekyll",               "3.9.5"
gem "wdm",                  ">= 0.2.0"
gem "kramdown-parser-gfm",  "~> 1.1"
gem "webrick",              "~> 1.8"
gem "jekyll-regex-replace", "~> 1.1"
gem "logger"
gem "csv"
gem "base64"
gem "bigdecimal"