Jekyll 4 on macOS 完整安装指南Homebrew chruby Ruby 版本管理实战【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll本指南基于 Jekyll 官方文档 docs/_docs/installation/macos.md讲解在 macOS 上从零搭建 Jekyll 开发环境的标准流程用 Homebrew 安装 chruby 与 ruby-install通过版本管理器安装受支持的 Ruby最后安装 Jekyll gem 并完成验证。读完本文你将掌握一套不污染系统、可随时切换 Ruby 版本、且能规避 macOS 系统 Ruby 各种坑的安装方案并了解安装失败时的 macOS 专属排错路径。支持的 macOS 版本与安装前置要求Jekyll 官方对 macOS 版本的支持策略与 Homebrew 保持一致通常支持最新的 23 个 macOS 大版本。更老的系统版本可能可以运行但官方不提供支持。与操作系统版本相比更关键的前置条件是 Ruby 环境。根据仓库内的数据文件 docs/_data/ruby.ymlRuby 最低版本要求为 2.7.0min_version: 2.7.0这与 jekyll.gemspec 中s.required_ruby_version 2.7.0的声明完全一致官方推荐的 Ruby 版本为 3.4.1current_version: 3.4.1对应输出ruby 3.4.1 (2024-12-25 revision 48d4efcb85)。此外通用安装要求还包括 RubyGems可用gem -v检查、GCC 与 Make可用gcc -v、make -v检查详见 docs/_docs/installation.md 的 Requirements 一节。文档内所有版本占位符{{ site.data.ruby.current_version }}等在站点构建时即由 docs/_data/ruby.yml 渲染成具体版本号。为什么不要使用 macOS 自带的系统 RubymacOS 虽然预装了 Ruby但官方文档明确不建议用它来安装 Jekyll原因主要有三点版本过旧系统 Ruby 往往远低于 Jekyll 要求的 2.7.0无法满足依赖约束权限受限从 macOS 10.11El Capitan引入 System Integrity ProtectionSIP后许多原本可写的系统目录变为只读把 gem 安装进系统目录会报错详见下文排错章节升级与隔离困难直接改动系统 Ruby 容易破坏系统工具链的依赖。正确的做法是使用版本管理器安装独立的、较新的 Ruby并在多个版本之间自由切换。官方文档列举了四款主流工具asdf、chruby、rbenv与rvm其中推荐chruby理由是它最简单、最不容易引发问题。chruby 本身不负责下载和编译 Ruby它只负责切换实际的 Ruby 安装由配套的ruby-install完成。Step 1安装 HomebrewHomebrew 是 macOS 上安装开发工具的最便捷途径Jekyll 安装流程中的 chruby、ruby-install 都通过它分发。在 Terminal 中执行官方安装脚本/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)安装完成后建议先运行brew doctor确认环境健康再进入下一步。Step 2安装 chruby 与 ruby-install并用其安装 Ruby2.1 安装两个工具brew install chruby ruby-install其中chruby负责在当前 shell 中切换 Ruby 版本轻量、无侵入ruby-install负责下载源码并编译指定版本的 Ruby。2.2 安装最新稳定版 RubyJekyll 官方文档给出的命令如下ruby-install ruby 3.4.1原文档此处使用站点数据占位符{{ site.data.ruby.current_version }}根据 docs/_data/ruby.yml 当前渲染值为3.4.1。安装前也可以运行ruby-install查看可用版本列表选择任意不低于 2.7.0 的稳定版本但建议跟随官方推荐的 3.4.1因为它与 jekyll.gemspec 声明的required_ruby_version 2.7.0及文档渲染值保持同步。该命令会从源码编译 Ruby需要几分钟时间。编译期间请确保已安装 Xcode Command Line Tools可用xcode-select --install安装否则会因缺少编译工具而失败。2.3 配置 shell 自动加载 chruby编译完成后将以下三行追加到 shell 配置文件中让每次打开终端都自动启用 chruby 并切换到目标 Ruby 版本echo source $(brew --prefix)/opt/chruby/share/chruby/chruby.sh ~/.zshrc echo source $(brew --prefix)/opt/chruby/share/chruby/auto.sh ~/.zshrc echo chruby ruby-3.4.1 ~/.zshrc # run chruby to see actual version默认写入~/.zshrcmacOS 的默认 shell 是 zsh如果使用 Bash则替换为~/.bash_profileauto.sh负责在进入包含.ruby-version文件的目录时自动切换版本如果对当前使用的 shell 不确定可在终端执行echo $SHELL查看。2.4 验证 Ruby 安装关闭并重新打开 Terminal让配置生效然后检查版本ruby -v输出应显示ruby 3.4.1 (2024-12-25 revision 48d4efcb85)或更新版本。如果显示的仍是系统 Ruby 版本说明 chruby 未生效请检查~/.zshrc中追加的三行是否在 PATH 相关配置之后。Step 3安装 JekyllRuby 就绪后直接通过 gem 安装 Jekyllgem install jekyll该命令会安装 Jekyll 本体及其全部运行时依赖。以当前仓库 jekyll.gemspec 为例Jekyll 4.4.1版本号定义于 lib/jekyll/version.rb的运行时依赖包括依赖版本约束用途liquid~ 4.0模板渲染引擎kramdown~ 2.3, 2.3.1Markdown 转换kramdown-parser-gfm~ 1.0GitHub Flavored Markdown 支持jekyll-sass-converter 2.0, 4.0Sass/SCSS 编译rouge 3.0, 5.0代码高亮mercenary~ 0.3, 0.3.6命令行参数解析pathutil、safe_yaml、terminal-table、webrick等见 gemspec路径处理、YAML 解析、表格输出、本地服务器安装完成后可验证jekyll -v正常会输出jekyll 4.4.1以当前仓库版本为准。jekyll可执行文件的入口位于 exe/jekyll它通过 Mercenary 注册source、destination、safe、plugins_dir等全局选项并支持从外部 gem如jekyll-serve按需注册子命令。安装后创建站点与日常构建命令环境搭建完成后即可创建第一个 Jekyll 站点jekyll new my-site cd my-site bundle exec jekyll serveJekyll 官方强烈推荐配合 Bundler 与Gemfile使用这样能锁定站点在不同机器上使用完全相同的 Jekyll 与插件版本。每个 Jekyll 站点根目录都有一份Gemfile基础形态为source https://rubygems.org gem jekyll group :jekyll_plugins do gem jekyll-feed gem jekyll-seo-tag end使用流程为gem install bundler只需安装一次→ 在含Gemfile的目录执行bundle install→ 之后一律用bundle exec jekyll serve启动。若未使用Gemfile则可直接运行jekyll serve。关于 Gem 与 Bundler 的基础概念可参考 docs/_docs/ruby-101.md。macOS 专属故障排查如果安装或运行出现问题以下是 macOS 上最常见的问题及官方给出的对策完整清单见 docs/_docs/troubleshooting.md。因 SIP 无法写入系统目录macOS 10.11 引入 SIP 后部分原可写目录变为系统保护目录直接gem install jekyll可能失败。两种官方建议方案将 gem 安装到允许的位置仅在必要时加sudogem install -n /usr/local/bin jekyll或改用 Homebrew 方案安装 Ruby 后再装 Jekyll即本文的主流程这样 gem 全部落在用户目录通常无需sudo。RubyGems 过旧或缺少编译工具更新 RubyGemsgem update --system安装/更新 Xcode Command Line Tools提供 gcc 等编译工具编译原生 gem 时必需xcode-select --install注意升级 macOS 不会自动升级 Xcode过旧的 Xcode.app 可能干扰 Command Line Tools此时应先在 App Store 升级 Xcode 再重新安装 Command Line Tools。ARM64Apple Silicon上的 ffi 问题Jekyll 兼容 ARM64 架构但bundle exec jekyll serve可能与旧版ffigem 冲突而失败。解决方法是更新依赖确保ffi版本不低于 1.14.2bundle update # 或手动指定版本 gem install ffi -v 1.14.2需要帮助时若上述方案仍无法解决可查阅 docs/_docs/troubleshooting.md覆盖各平台的安装与运行问题或在 Jekyll 官方论坛提问。macOS 之外的 Ubuntu、FreeBSD、其他 Linux 发行版与 Windows 安装指南统一收录于 docs/_docs/installation.md按系统选择对应子文档即可。小结在 macOS 上安装 Jekyll 的核心思路可归纳为三步用 Homebrew 装好 chruby 与 ruby-install → 用 ruby-install 编译受支持的 Ruby当前推荐 3.4.1最低 2.7.0→ 用 gem 安装 Jekyll 并配合 Bundler 管理站点依赖。这套流程避开了系统 Ruby 的版本与权限限制保留了随时切换 Ruby 版本的灵活性是 Jekyll 官方文档推荐且与当前仓库 jekyll.gemspec 版本约束完全对齐的安装方式。【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考