Serial Studio 帧发布热路径零分配优化：spec 0085 的 raw 值规则与 OpenEntry 重设计解析
2026/9/18 15:29:32
Jekyll 搭建指南：从零安装、创建第一个站点并用 build 与 serve 本地预览
【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll
本文基于 Jekyll 官方分步教程的第一步 "Setup" 展开，覆盖安装 Ruby 与 Jekyll、用 Bundler 管理项目依赖、创建第一个静态站点，以及使用jekyll build和jekyll serve构建与本地预览站点的完整流程。读完后，你能够独立搭好一套不依赖默认 gem 主题的工作环境，理解两个核心构建命令的差异，并知道为什么jekyll serve生成的站点不能直接用于部署。
安装 Jekyll
Jekyll 是一个 Ruby gem，因此第一步是在机器上安装 Ruby。官方文档按操作系统分别提供了安装说明，可参阅 安装指南 中针对 macOS、Windows、Ubuntu、FreeBSD 及其他 Linux 分发行版的章节。
Ruby 就绪后，在终端中安装 Jekyll 和 Bundler：
gem install jekyll bundler接下来创建Gemfile来声明项目依赖：
bundle init用文本编辑器打开生成的Gemfile，将 jekyll 加入依赖：
gem "jekyll"然后运行bundle为当前项目安装 jekyll。之后，本教程中列出的所有 jekyll 命令都可以加上bundle exec前缀，确保使用的始终是你Gemfile中锁定的那个 jekyll 版本，而不是全局安装的版本：
bundle exec jekyll serveJekyll 的命令行入口位于 exe/jekyll，命令解析与注册逻辑集中在 lib/jekyll/command.rb。
创建你的第一个站点
现在创建站点：新建一个目录作为站点根目录，名称随意，教程后续统一称其为root，例如my_site。
在 root 中初始化一个 Git 仓库也是合适的时机。Jekyll 的一个重要特点是没有数据库——站点的所有内容与结构都是文件，天然适合由 Git 仓库进行版本管理。使用 Git 是可选的但推荐的做法。
添加第一个文件：在root下创建index.html，内容如下：
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Home</title> </head> <body> <h1>Hello World!</h1> </body> </html>从源码可以印证这个站点的最小结构：Jekyll 的默认配置中，源目录就是当前工作目录，输出目录就是当前目录下的_site，见 lib/jekyll/configuration.rb：
"source" => Dir.pwd, "destination" => File.join(Dir.pwd, "_site"),也就是说，即使没有任何配置文件，Jekyll 也默认把“你在哪里运行命令”当作源目录，把./_site当作构建产物目录。
构建站点：jekyll build 与 jekyll serve
Jekyll 是静态站点生成器，必须先构建才能查看。可用的构建命令有两个：
jekyll build：构建站点并把静态产物输出到_site目录；jekyll serve：先执行jekyll build，再在http://localhost:4000启动本地 Web 服务器，并在每次文件变化时自动重新构建。
两个命令的底层调用链都经过 lib/jekyll/command.rb 中的process_site，由它调用Site#process完成读取、渲染与写出，并在捕获到致命错误时打印构建失败信息。
jekyll serve 的默认行为与源码依据
jekyll serve的默认端口和主机名由默认配置决定，见 lib/jekyll/configuration.rb：
"port" => "4000", "host" => "127.0.0.1",在 lib/jekyll/commands/serve.rb 的命令动作中可以看到两条关键逻辑：
opts["serving"] = true opts["watch"] = true unless opts.key?("watch") # ... config["url"] = default_url(config) if Jekyll.env == "development"第一处解释了为什么jekyll serve会自动开启文件监视（等价于--watch）：不重建一次你就看不到变化。第二处则解释了后文部署警告的成因——开发环境下url会被自动设置为http://localhost:4000（或--host/--port指定的值），站点内生成的链接和资产 URL 都会带上这个前缀。
开发时用 --livereload 自动刷新浏览器
开发期间推荐使用jekyll serve。若希望在每次改动时强制浏览器自动刷新，可加上--livereload：
bundle exec jekyll serve --livereload如果 4000 端口被占用，或希望改到其他主机/端口，使用--host和--port参数，完整选项说明见 serve 命令选项。LiveReload 的实现可以从源码中梳理出清晰链路：
- lib/jekyll/commands/serve.rb 定义 LiveReload 默认监听端口
LIVERELOAD_PORT = 35_729，并在register_reload_hooks中通过 Jekyll Hooks 的:site, :post_render与:site, :post_write钩子收集本次构建中被 增量重建器 标记为需要重新生成的页面，然后通知 LiveReload Reactor； - lib/jekyll/commands/serve/servlet.rb 中的
BodyProcessor会在响应阶段把 LiveReload 的<script>标签注入到 HTML 的<head>中，让浏览器连接到35729端口的 LiveReload 服务。
serve 常用命令行参数
serve在构建选项之外，还有一组专属选项，定义见 lib/jekyll/commands/serve.rb，与 serve 选项数据 一一对应：
| 选项 | 说明 |
|---|---|
-P, --port PORT | 监听端口，默认4000 |
-H, --host HOSTNAME | 绑定主机名，默认127.0.0.1（文档中写作localhost） |
-l, --livereload | 页面内容变化时自动刷新浏览器 |
--livereload-ignore GLOB1[,GLOB2,...] | LiveReload 忽略的文件 glob 模式（需加引号防止 shell 展开），模式会匹配资源的relative_path |
--livereload-min-delay SECONDS/--livereload-max-delay SECONDS | 自动刷新前的最小/最大延迟，必须与--livereload同用 |
--livereload-port PORT | LiveReload 监听端口，默认35729 |
-o, --open-url | 启动后自动在浏览器中打开站点 URL |
-B, --detach | 将服务器从终端分离到后台运行（与--livereload互斥，二者同用时会强制选择--livereload） |
--skip-initial-build | 跳过服务器启动前的首次构建 |
--show-dir-listing | 显示目录列表而不是加载 index 文件 |
--ssl-cert/--ssl-key | 提供 X.509 证书与私钥以启用 HTTPS，两者必须同时给出 |
serve同时接受全部构建选项，这些通用参数在 lib/jekyll/command.rb 的add_build_options中统一定义，常用的包括：
| 选项 | 说明 |
|---|---|
--config CONFIG_FILE[,CONFIG_FILE2,...] | 指定自定义配置文件 |
-d, --destination DESTINATION | 将站点输出到指定目录 |
-s, --source SOURCE | 指定自定义源目录 |
-w, --[no-]watch | 监视文件变化并重新构建（serve下默认开启） |
-b, --baseurl URL | 从指定 base URL 提供服务 |
--force_polling | 强制 watch 使用轮询方式 |
-D, --drafts | 渲染_drafts目录下的草稿 |
-q, --quiet/-V, --verbose | 静默输出 / 打印详细日志 |
-I, --incremental | 启用增量重建 |
--future | 允许发布日期在未来的文章 |
另外，若站点目录下存在404.html，serve 会用它替换服务器错误页，逻辑见 lib/jekyll/commands/serve/servlet.rb。
构建后验证
运行jekyll serve，然后在浏览器中打开http://localhost:4000，你应该能看到 "Hello World!"。
此时你可能会想：“这不就是 Jekyll 把一个 HTML 文件从一个地方复制到另一个地方吗？”——没错，这就是静态站点生成器的基本工作：读取源文件、经过转换器与渲染器处理、写出静态产物。耐心的年轻人，后面还有 Liquid 模板、布局、Includes 等大量内容要学。
注意：serve 生成的站点不能直接部署
需要特别警惕的一点：jekyll serve构建在_site中的版本不适合部署。由它构建的站点里，链接和资产 URL 会使用http://localhost:4000（或命令行配置的值），而不是你在 站点配置文件 中设置的生产环境值。其根源就是前述 lib/jekyll/commands/serve.rb 中在开发环境下自动注入url的行为。当站点准备好部署时，应使用不带 serve 的正式构建方式，详见教程的 部署章节。
下一步
完成本步后，你可以继续教程的第二步，学习 Liquid 模板语法与模板化渲染，参见 Liquid 指南。
【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考