为什么要折腾本地预览？

在直接使用 GitHub 网页版写了几篇博文后，我发现无法实时预览排版是一个巨大的痛点。为了追求更高效的创作体验，我决定在本地搭建 Jekyll 环境。虽然过程充满了”红字报错”，但最终成功的时刻非常有成就感。

核心配置流程

1. 搭建 Ruby 基础

我选择了 Ruby+Devkit 3.4.8-1 (x64) 版本。完整流程如下：

打开 RubyInstaller 官方下载页获取最新的 Ruby+Devkit 3.4.x (x64)。
安装向导中务必勾选 Add Ruby to PATH，确保终端能直接调用 ruby 与 gem。
安装完成后保持勾选 Run ridk install to set up MSYS2 and development toolchain，点击 Finish。
随后在弹出的命令行窗口依次输入 1、2、3，或者直接输入 3 运行“MSYS2 and MINGW development toolchain”安装，确保 MSYS2 组件完备。

至此，Ruby 与 MSYS2 工具链准备完毕，为后续编译复杂的 Gem 插件打下了地基。

2. 更换国内下载源（强烈建议）

为了避免下载太慢或中途失败，请在命令行窗口中依次输入以下命令：

gem sources --add https://gems.ruby-china.com/ --remove https://rubygems.org/

确认源切换成功：

gem sources -l

执行后应该显示只有 https://gems.ruby-china.com/ 这一个源。

安装 Jekyll 引擎

输入最重要的命令：

gem install jekyll bundler

3. 创建标准 Gemfile 配置

管理员身份运行 cmd，在你的博客文件夹里找到 Gemfile，用记事本打开，删除里面所有内容，只粘贴下面这段最标准、兼容性最好的配置：

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

# 使用 GitHub Pages 官方推荐的依赖包
gem "github-pages", group: :jekyll_plugins

# 解决 Windows 环境下的时区和运行环境问题
gem "tzinfo-data", platforms: [:mingw, :mswin, :x64_mingw, :jruby]
gem "webrick"

强制重新安装

回到命令行窗口，依次输入：

del Gemfile.lock

这会删除旧的锁定文件，打破版本僵局。

bundle install

4. 解决版本冲突

通过精简 Gemfile 并强制使用 GitHub 官方推荐的依赖包，我成功化解了冲突。这个配置经过多次测试，在 Windows 环境下具有最好的兼容性。

如何开启预览？

现在，我只需要在博客根目录下打开终端，输入：

bundle exec jekyll serve

然后在浏览器访问 http://localhost:4000，就能看到与线上完全一致的排版效果。每一次保存修改，页面都会自动刷新，这种”所见即所得”的感觉才是真正的写作享受。

一键启动脚本（可选）

为了更方便地启动预览，可以创建一个 START_BLOG.bat 批处理文件：

@echo off
:: 设置代码页为UTF-8，防止中文乱码导致闪退
chcp 65001 >nul
title 我的博客本地预览引擎

echo ==========================================
echo   正在准备启动 Jekyll 本地服务器...
echo ==========================================

:: 1. 切换到当前脚本所在的盘符和目录
%~d0
cd %~dp0

:: 2. 检查并强制更新依赖（解决可能的版本冲突）
echo [步骤 1/3] 正在同步插件依赖...
call bundle install
if %errorlevel% neq 0 (
    echo.
    echo ❌ 依赖同步失败！请检查 Gemfile 或网络。
    pause
    exit /b 1
)

:: 3. 启动预览（增加 --trace 参数以便报错时显示详细原因）
echo.
echo [步骤 2/3] 正在开启本地服务器...
echo ------------------------------------------
echo 🌐 预览地址: http://localhost:4000
echo ⏹️  停止服务器: 请直接关闭此窗口或按 Ctrl+C
echo ------------------------------------------
echo.

bundle exec jekyll serve --livereload

:: 4. 如果程序意外退出，保持窗口不关闭
if %errorlevel% neq 0 (
    echo.
    echo ❌ 服务器意外停止，请查看上方报错信息。
    pause
)

将这个文件保存在博客根目录，每次预览时双击运行即可。这个脚本的优势：

自动处理依赖：每次启动前自动运行 bundle install 确保依赖最新
错误处理：包含完整的错误检测和提示
实时重载：使用 --livereload 参数，修改文件后浏览器自动刷新
中文支持：设置 UTF-8 编码，避免中文乱码问题
友好界面：清晰的步骤提示和预览地址显示

特别鸣谢：在 Gemini 的耐性指引下，我顺利走通了这段硬核的配置之路。