# wp-category-json-to-sql

**Repository Path**: souyunku/wp-category-json-to-sql

## Basic Information

- **Project Name**: wp-category-json-to-sql
- **Description**: 用 JSON 描述 WordPress 分类与分类 SEO，生成 SQL，通过 mysql 客户端写入数据库。无需插件、不执行 WordPress PHP
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-01
- **Last Updated**: 2026-04-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# wp-category-json-to-sql

> 用 JSON 描述 WordPress 分类与分类 SEO，生成 SQL，通过 `mysql` 客户端写入数据库。无需插件、不执行 WordPress PHP。

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3](https://img.shields.io/badge/python-3.6+-blue.svg)](https://www.python.org/downloads/)

## 简介

本仓库提供一组 **Shell + Python（标准库）** 脚本：从 `categories.json` 生成 `INSERT` 等语句，写入 `{表前缀}_terms`、`{表前缀}_term_taxonomy`，并在 `{表前缀}_options` 中写入 `_taxonomy_meta_{term_id}`（PHP 序列化，含 SEO 字段）。适合把分类当作配置用 Git 管理，并在 CI 或多环境中重复执行。

数据流概览：

```text
categories.json → generate_sql.py → SQL → mysql → WordPress 数据库
```

生成的 SQL 包裹在 `START TRANSACTION` … `COMMIT` 中；支持 `--stdout` 管道导入，也可选择写出 `import_categories.sql`。

## 功能特性

- JSON 描述分类：`name`、`slug`、`description`、嵌套 `seo`（title / keywords / description）
- SEO 按 PHP `serialize` 规则生成（UTF-8，长度按字节）
- `import.sh` + `import.conf`（或命令行参数）连接远程/通用环境
- `import_local.sh` 为本地示例脚本（需按环境修改其中的连接信息）
- 可选 `parse_sql_to_json.py`：从 SQL 反向得到 JSON
- 与部分通过 `get_option("_taxonomy_meta_{$term_id}")` 读取分类 SEO 的主题兼容

**说明**：这不是 WordPress 插件；需要本机可执行 shell、已安装 `mysql` 客户端，且数据库账号有权写入上述表。

## 环境要求

- Python 3.6+
- `mysql` 命令行客户端
- 对 `{前缀}_terms`、`{前缀}_term_taxonomy`、`{前缀}_options` 的写入权限

下文命令默认在仓库根目录执行：

```bash
cd wp-category-json-to-sql
```

## 安装

```bash
git clone https://gitee.com/souyunku/wp-category-json-to-sql.git
cd wp-category-json-to-sql
chmod +x import.sh import_local.sh
cp import.conf.example import.conf
# 编辑 import.conf，勿将含密码的文件提交到公开仓库
```

若使用 GitHub，将 clone 地址换成你的仓库 URL 即可。

## 快速开始

1. **准备数据**  
   复制 `categories.example.json` 为 `categories.json`（`categories.json` 已在 `.gitignore` 中，不会被提交）。

2. **导入**  

   ```bash
   ./import.sh
   ```

   或显式传入连接信息：

   ```bash
   ./import.sh <主机> <用户> <密码> <数据库名> [表前缀]
   ```

3. **本地示例**（脚本内为示例用连接信息，使用前请改为你的本机配置）

   ```bash
   ./import_local.sh
   ```

## 配置文件：`import.conf.example` → `import.conf`

`import.sh` 会把配置文件当作 **Bash 片段**执行（`source`），从而读取变量。仓库里只有模板 **`import.conf.example`**，本地需执行 `cp import.conf.example import.conf` 后编辑 **`import.conf`**。该文件已在 `.gitignore` 中，避免把密码提交进仓库。

模板内容如下（值请换成你的环境）：

```bash
# 复制为 import.conf 后填写（公开仓库勿提交真实密码）
# cp import.conf.example import.conf

HOST="127.0.0.1"
USER="wordpress"
PASSWORD="change-me"
DATABASE="wordpress"
# 表前缀不要带末尾下划线（wp 对应 wp_terms）
TABLE_PREFIX="wp"
```

| 变量 | 含义 |
|------|------|
| `HOST` | MySQL 地址，如 `127.0.0.1`、`localhost` 或远程主机名 |
| `USER` | 数据库用户名（需对 WordPress 相关表有读写权限） |
| `PASSWORD` | 数据库密码 |
| `DATABASE` | WordPress 站点使用的数据库名 |
| `TABLE_PREFIX` | 表前缀，**不要**带末尾下划线；`wp` 表示表名为 `wp_terms`、`wp_term_taxonomy` 等。若误写成 `wp_`，`import.sh` 会自动去掉尾部 `_` |

若通过环境变量 **`IMPORT_CONFIG=/path/to/其它.conf`** 指定路径，则使用给定文件代替默认的 `./import.conf`。命令行传入「主机、用户、密码、库名」四个参数时，会覆盖配置文件里的 `HOST` / `USER` / `PASSWORD` / `DATABASE`；表前缀仍由第 5 个参数或 `TABLE_PREFIX` 决定（见下一节）。

## `import.sh` 行为说明

| 项 | 说明 |
|----|------|
| 连接信息 | 默认读 `./import.conf`（或 `IMPORT_CONFIG`）；前 4 个命令行参数可覆盖主机、用户、密码、库名 |
| 表前缀 | 第 5 个参数，或 `import.conf` 中的 `TABLE_PREFIX`；**不要**带末尾下划线；若写成 `wp_` 脚本会规范化。未配置时默认为 `wp` |
| JSON 路径 | 环境变量 `CATEGORIES_JSON`；默认脚本同目录下的 `categories.json` |

导入过程中若选择「清理」，将删除 `term_id > 1` 的相关术语及 `_taxonomy_meta_%` 选项（详见下文「清理与备份」）。

## `categories.json` 格式

UTF-8 编码的 JSON 数组，示例：

```json
[
  {
    "name": "分类名称",
    "slug": "category-slug",
    "description": "分类描述（写入 term_taxonomy）",
    "seo": {
      "title": "SEO 标题",
      "keywords": "关键词1, 关键词2",
      "description": "SEO 描述"
    }
  }
]
```

## `generate_sql.py`

```text
python3 generate_sql.py [表前缀] [--stdout] [--json <路径>]
```

- **表前缀**：省略时脚本默认 `dk`；导入 WordPress 默认表前缀时请显式传入，例如 `wp`。
- **`--stdout`**：SQL 输出到标准输出（提示信息在 stderr），便于管道到 `mysql`。
- **`--json`**：指定 JSON 文件，默认脚本同目录下的 `categories.json`。

```bash
python3 generate_sql.py wp --stdout --json ./categories.json | mysql -h HOST -u USER -pPASS DBNAME
python3 generate_sql.py wp
# 上式可在当前目录生成 import_categories.sql（未使用 --stdout 时）
```

## 环境变量

| 变量 | 含义 |
|------|------|
| `CATEGORIES_JSON` | 分类 JSON 文件路径 |
| `IMPORT_CONFIG` | `import.sh` 使用的配置文件路径（默认 `./import.conf`） |

## 清理与备份

若确认执行清理逻辑，脚本将：

1. 删除 `{前缀}_options` 中 `option_name` 匹配 `_taxonomy_meta_%` 的行  
2. 删除 `{前缀}_terms`、`{前缀}_term_taxonomy` 中 `term_id > 1` 的行  
3. 将相关表的 `AUTO_INCREMENT` 调整为从 `2` 起  

**影响范围不限于本次导入产生的数据。** 生产环境务必先备份数据库。

## 目录结构

```text
.
├── README.md
├── LICENSE
├── .gitignore
├── categories.example.json    # JSON 结构示例
├── import.conf.example        # 复制为 import.conf
├── generate_sql.py
├── import.sh
├── import_local.sh
└── parse_sql_to_json.py
```

`categories.json`、`import.conf`、`import_categories.sql` 由本地生成或自备，已通过 `.gitignore` 排除。

## 与主题的关系

分类落在 `{前缀}_terms` 与 `{前缀}_term_taxonomy`（`taxonomy = 'category'`）。部分主题在 `{前缀}_options` 使用 `_taxonomy_meta_{term_id}` 存储序列化 SEO 数据；若你的主题约定不同，可在本仓库基础上修改 `generate_sql.py`。

## 导入后抽查（表前缀 `wp` 时示例）

```bash
mysql -h HOST -u USER -pPASS DBNAME -e \
  "SELECT t.term_id, t.name, t.slug FROM wp_terms t
   JOIN wp_term_taxonomy tt ON t.term_id = tt.term_id
   WHERE tt.taxonomy = 'category' AND t.term_id > 1
   ORDER BY t.term_id;"
```

## 常见问题

| 现象 | 处理方向 |
|------|----------|
| 提示缺少数据库配置 | 检查 `import.conf` 或是否传入 4 个连接参数 |
| `Access denied` | 核对账号、授权主机、网络与防火墙 |
| 数据写入错误表 | 核对 `TABLE_PREFIX` 是否与真实表前缀一致 |
| `import_local.sh` 失败 | 是否仍使用脚本内的示例账号/库名/前缀 |
| 修改 JSON 后无变化 | 是否指向了正确的 `CATEGORIES_JSON`；是否需要先清理再导入 |
| 中文乱码 | 数据库与表使用 `utf8mb4`；JSON 以 UTF-8 无 BOM 保存 |

## 贡献

欢迎通过 Issue、Pull Request 反馈与改进；请保持改动范围小、与现有脚本风格一致。

## 开发团队

本项目由 **[DDKK 技术团队](https://www.ddkk.com/)** 提供技术支持。

| 项目 | 信息 |
|:--|:--|
| 官网 | [https://www.ddkk.com](https://www.ddkk.com/) |
| 邮箱 | admin@ddkk.com |
| 微信 | itdevtools |

欢迎提交 Issue 和 PR，也欢迎加微信交流技术。

---

## 许可证

MIT License