Jekyll 快速上手：用 `jekyll new` 与 `jekyll serve` 一分钟启动本地博客站点

Jekyll 快速上手：用jekyll new与jekyll serve一分钟启动本地博客站点

【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll

Jekyll 是使用 Ruby 编写的博客感知型静态站点生成器，本指南以仓库教程文档 test/source/_tutorials/lets-roll.md 为核心骨架，讲解"从安装完成到浏览器中看到自己的第一个站点"的完整过程：先用jekyll new生成站点骨架，再用bundle exec jekyll serve在本地启动服务。读完本文，你将掌握 Jekyll 新站点脚手架命令与本地预览命令的完整用法、底层执行流程和常用参数，并能立刻动手跑起自己的第一个 Jekyll 项目。

这份教程在仓库中的位置

lets-roll.md是仓库测试源目录（test/source/_tutorials/）中一套 6 节入门教程的第 2 节（lesson: 2，预计耗时 1 分钟）。整套教程的脉络是：

Lesson	文件	主题
1	test/source/_tutorials/getting-started.md	安装 Ruby（前置条件）
2	test/source/_tutorials/lets-roll.md	创建站点并本地预览（本文主题）
3	test/source/_tutorials/dive-in-and-publish-already.md	Markdown 与 Kramdown 转换
4	test/source/_tutorials/tip-of-the-iceberg.md	深入学习指引
5	test/source/_tutorials/extending-with-plugins.md	插件扩展
6	test/source/_tutorials/graduation-day.md	毕业小结与社区反馈

原始教程正文只有两条命令，但背后的执行细节远不止于此。下面结合仓库源码逐条拆解。

前置条件：Ruby、Jekyll 与 Bundler

本教程的前提是第 1 节 getting-started.md 已完成：系统里装好了Ruby、Jekyll和Bundler。Jekyll 本体是一个 Ruby gem，Bundler 则负责锁定依赖版本——这正是后续要使用bundle exec前缀的原因。本仓库的 Gemfile 与 jekyll.gemspec 展示了 Jekyll 自身的依赖管理方式，新站点生成时也会附带一份独立的 Gemfile（详见下文）。

第一步：jekyll new my blog创建站点骨架

在终端输入教程给出的命令：

$ jekyll new my blog

命令语法与路径处理

new命令的语法是new PATH，见 lib/jekyll/commands/new.rb。注意这里 "my" 和 "blog" 之间有一个空格，这是有意为之的：从源码看，new_blog_path = File.expand_path(args.join(" "), Dir.pwd)（new.rb）会把所有参数用空格连接成路径，因此jekyll new my blog等价于创建一个名为my blog（带空格）的目录——无需手动加引号。若在多个参数间不加空格（如jekyll new my-blog），则会创建my-blog目录。

源码视角：命令内部做了什么

从 new.rb 的process方法可以看到完整执行流程：

1. 校验参数：未提供路径时抛出ArgumentError（"You must specify a path."）；
2. 创建目录：FileUtils.mkdir_p new_blog_path；
3. 冲突检查：调用preserve_source_location?（new.rb），若目标目录非空且未加--force，会报错 "exists and is not empty"，并提示用--force覆盖；
4. 生成脚手架：默认模式调用create_site，复制 lib/site_template 下的全部文件；
5. 写入示例文章：按_posts/YYYY-MM-DD-welcome-to-jekyll.markdown命名（new.rb），内容来自_posts/0000-00-00-welcome-to-jekyll.markdown.erb模板；
6. 生成 Gemfile：内容由gemfile_contents方法内嵌生成（new.rb）；
7. 自动执行bundle install：after_install（new.rb）会在新站点目录内自动运行 Bundler 安装依赖，除非使用了--blank或--skip-bundle。

生成的项目结构

执行成功后，my blog目录里包含（对应 lib/site_template 目录）：

my blog/ ├── _config.yml # 站点全局配置 ├── _posts/ │ └── 2026-09-18-welcome-to-jekyll.markdown # 带日期的示例文章 ├── about.markdown # "关于"页面 ├── index.markdown # 首页（layout: home） ├── 404.html # 自定义 404 页面 └── Gemfile # 依赖清单

生成的 _config.yml 中包含title、email、description、baseurl、url等站点级配置，以及theme: minima与plugins: [jekyll-feed]两个构建配置项。生成的 index.markdown 只有极简的 Front Matter（layout: home），说明首页内容完全交给主题渲染。

生成的 Gemfile 核心内容（new.rb）：

gem "jekyll", "~> #{Jekyll::VERSION}" gem "minima", "~> 2.5" # 默认主题 group :jekyll_plugins do gem "jekyll-feed", "~> 0.12" # RSS feed 插件 end

此外还为 Windows/mingw/JRuby 平台按需引入tzinfo、tzinfo-data、wdm、http_parser.rb等平台相关 gem。

new命令参数一览

参数	作用	源码位置
--force	目标目录已存在且有内容时强制覆盖	new.rb
--blank	生成空脚手架（仅目录与基础模板，不写示例文章与 Gemfile）	new.rb
--skip-bundle	跳过自动执行的bundle install	new.rb

--blank模式会额外创建_data、_drafts、_includes、_posts空目录（new.rb），适合从零手工搭建的场景。

第二步：bundle exec jekyll serve本地预览

接着教程要求执行：

$ bundle exec jekyll serve

然后在浏览器中访问http://localhost:4000。

为什么要用bundle exec

生成的 Gemfile 注释中明确写道："Run Jekyll withbundle exec"——bundle exec会确保运行的是 Gemfile.lock 锁定的 Jekyll 版本，避免与系统全局 gem 版本不一致导致的构建差异。这是 Jekyll 官方推荐的标准启动方式。

源码视角：serve 命令发生了什么

serve命令定义在 lib/jekyll/commands/serve.rb，并注册了别名server与s。关键行为：

• 自动开启 watch：opts["watch"] = true unless opts.key?("watch")（serve.rb），即默认监听源文件变化并增量重建；
• 内置 WEBrick HTTP 服务器：start_up_webrick（serve.rb）创建WEBrick::HTTPServer，以destination（默认_site）为 DocumentRoot 提供服务；
• 打印访问地址：server_address/format_url（serve.rb）格式化输出http://<host>:<port>/，即教程中的http://localhost:4000（默认端口 4000，本教程文档即以此地址为准）；
• Ctrl-C 优雅停止：start_callback（serve.rb）在服务就绪后打印Server running... press ctrl-c to stop.，boot_or_detach（serve.rb）注册INT信号处理器来关闭服务器。

也就是说，jekyll serve一次完成"构建 + 起本地服务 + 监听文件变更"三件事，改完 Markdown 保存后浏览器刷新即可看到效果。

serve常用参数

完整参数表定义于 serve.rb：

参数	作用
-o, --open-url	启动后自动在浏览器打开站点
-l, --livereload	启用 LiveReload，文件变更后自动刷新浏览器
--livereload-port [PORT]	LiveReload 监听端口（默认 35729）
-P, --port [PORT]	HTTP 服务端口（默认 4000）
-H, --host [HOST]	绑定主机地址
-B, --detach	后台运行服务器
--ssl-cert [CERT]/--ssl-key [KEY]	启用 HTTPS（两者必须同时提供）
--skip-initial-build	跳过启动前的首次构建
--show-dir-listing	显示目录列表而非加载 index 文件

几个组合使用示例：

# 启动并自动打开浏览器 $ bundle exec jekyll serve --open-url # 启用 LiveReload，改文件自动刷新 $ bundle exec jekyll serve --livereload # 指定端口并在后台运行 $ bundle exec jekyll serve --port 8080 --detach

注意：--livereload与--detach互斥（会告警并强制改为 livereload），且 LiveReload 不支持 SSL；而--livereload-port等参数若未搭配--livereload使用会直接报错（serve.rb）。

常见坑与排查要点

结合源码与模板注释，以下三个细节最容易踩坑：

1. _config.yml改动不会热重载：生成的 _config.yml 注释明确说明，配置文件在bundle exec jekyll serve运行期间不会自动重新加载，修改后必须重启服务进程。
2. 目标目录非空：jekyll new遇非空目录会拒绝创建，提示使用--force；请确认目录内容确可覆盖再使用该参数。
3. 端口被占用：默认 4000 被占用时，用-P指定新端口，访问地址相应变为http://localhost:<port>。

下一步：继续这套教程

站点能跑起来之后，可以沿着教程系列继续深入：

• dive-in-and-publish-already.md（第 3 节）：了解 Jekyll 默认将 Markdown 转换为 HTML 的机制（Kramdown 是默认 Markdown 渲染器，可参考 lib/jekyll/converters/markdown.rb）；
• extending-with-plugins.md（第 5 节）：通过官方与社区插件扩展 Jekyll 能力；
• 仓库正式文档中的 docs/_docs/usage.md 与 docs/_docs/structure.md 介绍了完整的命令用法与目录结构；docs/_docs/configuration/options.md 汇总了全部配置项；
• 想了解new/serve命令的自动化验证方式，可阅读 test/test_new_command.rb 与 test/test_commands_serve.rb。

总结

两条命令，一分钟，这就是 Jekyll 的"零门槛"体验：jekyll new my blog基于 lib/site_template 生成带示例文章、Gemfile 与 minima 主题的完整骨架并自动安装依赖；bundle exec jekyll serve则用 WEBrick 在http://localhost:4000提供构建后的站点，并默认开启文件监听。掌握这两个命令及其参数（--force、--blank、--livereload、--port、--open-url等），你就拥有了 Jekyll 日常开发最核心的工作流——创建、预览、迭代、发布。

【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll