WordPress 网站向 Jekyll 静态博客迁移全记录 | 笔记

一、安装 Jekyll

1.安装 Ruby+Devkit for Windows

访问 RubyInstaller for Windows 网站。
下载最新版本的 Ruby+Devkit 安装包（推荐使用最新稳定版，例如 3.X.X-X64）。选择带有 Devkit 的版本非常重要，因为它包含了编译本地扩展所需的工具。
运行安装程序。
在安装过程中，确保勾选 “Add Ruby executables to your PATH”（添加到环境变量），这样你就可以在任何地方运行 Ruby 命令。
安装完成后，会弹出一个命令行窗口，运行 ridik install 或类似命令来完成 MSYS2/MinGW 的安装。如果这个窗口没有自动弹出，你可以在命令提示符中运行 ridik install。按照提示选择你需要安装的组件（通常是 MSYS2 base installation 和 MSYS2 system update）。

2.安装 Bundler

打开命令提示符（或 PowerShell）。
运行以下命令安装 Bundler：

gem install bundler

3.安装 Jekyll

仍然在命令提示符中，运行以下命令：

gem install jekyll

4.验证安装

运行以下命令检查 Jekyll 是否安装成功：

jekyll -v

其他命令请参考jekyll 官网。

二、从 WordPress 导出数据

1.本地安装 XAMPP

XAMPP：集成了 Apache + MySQL + PHP
访问XAMPP Installers and Downloads for Apache Friends网站，下载安装即可。

2.准备好打包好的 Wordpress 文件夹和导出的 sql 数据库文件

将整个 wordpress 文件夹放在\xampp\htdocs 里，取名为 wordpress
打开 XAMPP 控制面板，启动 Apache 和 MySQL
打开浏览器，访问 http://localhost/phpmyadmin\ 在 XAMPP 中，MySQL 默认的用户名和密码如下：
用户名（Username）： root
密码（Password）：空（即没有密码）
新建一个数据库（名字可以是 wordpress）
导入你复制下来的 wordpress.sql 数据。
配置 wp-config.php

define('DB_NAME', 'wordpress');
/** MySQL数据库用户名 */
define('DB_USER','root');
/** MySQL数据库密码 */
define('DB_PASSWORD','');
/** MySQL主机 */
define('DB_HOST','localhost');

配置.htaccess
删去 https 重定向等所有重定向，甚至可以直接清除内容。
删去各种缓存插件的缓存目录和缓存插件（最好在导出来之前就清空停用）
进入本地 MySQL 后台（http://localhost/phpmyadmin）\ 找到刚才新建的 wordpress 数据库，进入 wp_options（我的是 ggvag_options，也可能是其他表头）
修改 siteurl 和 home 为 http://localhost/wordpress/（名称和放在\\xampp\\htdocs 里的文件夹同名）

3.访问 Wordpress 用 WordPress to Jekyll Exporter 插件导出 jekyll-export

访问 wordpress 登录地址：http://localhost/wordpress/wp-login.php\ 安装 WordPress to Jekyll Exporter 插件。
运行插件导出 jekyll-export.zip 即可。

如果这里报错，Fatal error: Uncaught Error: Class “ZipArchive” not found
打开 php.ini 配置文件
打开 XAMPP 控制面板
点击 Apache 行右边的 Config → 选择 php.ini
在 php.ini 文件中查找以下一行：
;extension=zip
把前面的分号 ; 去掉，改成：
extension=zip
重启 Apache（点击 Apache 的 Stop，再 Start）

如果是媒体库数据过大的报错，如超过 1GB 编辑 php.ini（在 XAMPP 控制面板 Apache → Config → php.ini），搜索并修改以下参数：

; 允许上传的最大文件大小
upload_max_filesize = 2048M

; POST 提交数据的最大大小
post_max_size = 2048M

; PHP 脚本最大执行时间（单位：秒）
max_execution_time = 300

; PHP 脚本最大内存使用（推荐 512M 或更高）
memory_limit = 512M

修改完 php.ini 后，务必回到 XAMPP 控制面板，重启 Apache（点击 Apache 的 Stop，再 Start）

三、下载配置 Jekyll 主题文件并规范导出的 md 文件

1.下载 Jekyll 主题文件并配置运行环境

下载你想要使用的 Jekyll 主题到本地，如 https://github.com/Simpleyyt/jekyll-theme-next\ 解压到如 \blog 目录。
进入 \blog 目录，运行终端，运行——

bundle exec jekyll serve

一般来说会报错。直接将错误信息喂给 ai，它通常会指引你修改 \blog 目录下的 Gemfile 文件，以及安装各种依赖。如在 Gemfile 文件中添加：

gem 'webrick'
gem 'csv'
gem 'fiddle'
gem 'faraday-retry'
gem 'wdm', '>= 0.1.0', platforms: \[:mingw, :mswin, :x64\_mingw, :jruby\]

然后运行：

bundle install

有任何错误提示都可以问问神奇的 ai
直到 bundle exec jekyll serve 运行成功为止。

根据主题文件的说明，自行配置好 _config.yml 文件，以及其他单独的网址 md 文件，如 next 主题的单独的页面就是在根目录下的 1级文件夹下名称为 index.md 的文件。
以下都是基于 next 主题配置的说明，原理是一样的，只是可能存放的位置不同罢了。
将解压的 \jekyll-export 下的 wp-content 目录整个复制到 \blog\assets 下。
将解压的 \jekyll-export\_posts 下的所有 md 文件复制到 \blog\_posts 下。
运行 bundle exec jekyll serve ，查看网址。
这里一般会有很多格式错误，我们需要利用 python 脚本批量调整 md 文件。

2.批量调整 md 文件

访问Download Python | Python.org，下载安装 python 运行 bundle exec jekyll serve 后，可以自行修改调试 md 文件，它会同步更新，直到变成你希望的排版和页面，记住这些更改，寻找规律。
通常来说，你需要更新图片链接并去掉 wordpress 的区块头尾代码。如——

删除
</figure>
<figure class="wp-block-image size-full">
<figure class="wp-block-image size-large">
<figure class="wp-block-image size-full is-resized">
<figure class="wp-block-image size-large is-resized">
<figure class="wp-block-image">
<figure class="wp-block-gallery has-nested-images columns-default is-cropped">
<figure class="wp-block-table has-small-font-size">
<figcaption class="wp-element-caption">
<figcaption>
</figcaption>
<figure class="wp-block-audio">
<div class="wp-block-getwid-table-of-contents is-style-default">
</div>
https://ffani.com

/wp-content/uploads
替换为
/assets/wp-content/uploads

将这些你找到的信息发给 ai，让它给你写一个批量处理脚本。如——

import os
import sys

# --- 配置 ---

# 要删除的字符串列表
# 注意：处理顺序很重要，将更具体的标签放在前面
strings_to_delete = [
    '</figure>',
    '<figure class="wp-block-image size-full is-resized">',
    '<figure class="wp-block-image size-large is-resized">',
    '<figure class="wp-block-image size-full">',
    '<figure class="wp-block-image size-large">',
    '<figure class="wp-block-image">',
    '<figure class="wp-block-gallery has-nested-images columns-default is-cropped">',
    '<figure class="wp-block-table has-small-font-size">',
    '<figure class="wp-block-audio">',
    '</figcaption>',
    '<figcaption class="wp-element-caption">',
    '<figcaption>',
    '<div class="wp-block-getwid-table-of-contents is-style-default">',
    '</div>',
    'https://ffani.com',
]

# 要替换的字符串字典
# 格式为：'原始字符串': '新字符串'
strings_to_replace = {
    '/wp-content/uploads': '/assets/wp-content/uploads'
}

# --- 脚本主逻辑 ---

def process_markdown_files():
    """
    处理当前目录下的所有 Markdown 文件。
    """
    # 获取当前工作目录
    current_directory = os.getcwd()
    print(f"正在扫描目录: {current_directory}\n")

    # 存储被修改过的文件列表
    processed_files = []

    # 遍历当前目录下的所有文件
    for filename in os.listdir(current_directory):
        if filename.endswith(".md"):
            file_path = os.path.join(current_directory, filename)

            try:
                with open(file_path, 'r', encoding='utf-8') as f:
                    content = f.read()
            except Exception as e:
                print(f"错误：无法读取文件 {filename}: {e}")
                continue

            original_content = content

            # 1. 执行删除操作
            for item in strings_to_delete:
                content = content.replace(item, '')

            # 2. 执行替换操作
            for old, new in strings_to_replace.items():
                content = content.replace(old, new)

            # 3. 检查内容是否有变化，如果有则写回文件
            if content != original_content:
                try:
                    with open(file_path, 'w', encoding='utf-8') as f:
                        f.write(content)
                    processed_files.append(filename)
                except Exception as e:
                    print(f"错误：无法写入文件 {filename}: {e}")

    # 4. 返回处理结果
    if processed_files:
        print("--- 处理完成 ---")
        print("以下文件已被成功处理：")
        for f in processed_files:
            print(f"- {f}")
    else:
        print("--- 处理完成 ---")
        print("没有找到需要修改的文件。")

if __name__ == "__main__":
    process_markdown_files()

复制下来，保存到本地，取名为 1.py
备份好所有 md 文章，将 1.py 放入 md 同目录，右键打开终端，运行：

python 1.py

修改好 md 文件后再重新运行 bundle exec jekyll serve，如果还是有问题请多次修改。
如果你经常需要 wordpress 转 jekyll，你需要在写文章时——
（1）使用最新的区块编辑器，18 年底之前的文章是使用的经典编辑器，全部修改替换调整一下
（2）不使用任何图片、音乐批注，而是换成图片、音乐下加段落区块的形式
（3）少使用特殊的区块，不使用其他插件提供的区块

3.获取 jekyll 网站内容

再配置好环境，并调整完 md 文件后，再次运行 bundle exec jekyll serve
在 \blog\_site 目录下就是我们需要上传到 github 的文件了。

四、上传到 GitHub

1.安装 git

访问 Git 官网的下载页面。
关键步骤：在 “Adjusting your PATH environment”（调整您的 PATH 环境）这一步，请确保选择了推荐的选项 “Git from the command line and also from 3rd-party software”。这能让您在命令提示符（Cmd）、PowerShell 和其他工具中直接使用 git 命令。

2.上传到 GitHub

创建 Pages 服务并部署自己的静态网站后，打开终端。

# git clone https://github.com/username/projectname.github.io.git
# cd projectname.github.io
git add .
git commit  -m  "20250607"
# git config --global user.name "123"
# git config --global user.email "123@email.com"
git push -u origin main

真正关键的就是没有注释掉的那几步，如果遇到了任何报错，请直接发送给 ai，谢谢喵~