WP转ZS（WordPressToZsadmin）使用文档

作者：kuakeba.cn | 版本：1.0.0 | 适用于 Zsens Admin 3.0+（PHP 8.2+，需 pdo_mysql）

一、插件简介

将 WordPress 网站转换为 zsadmin 网站：插件直连 WordPress 的 MySQL 数据库，把分类、文章（含评论）、页面迁移到社区插件（community）对应数据表。

• 迁移范围：WP 分类 → 社区分类；WP 已发布文章 → 社区文章（主题）；WP 已发布页面 → 社区页面；WP 已通过评论 → 社区评论（保留楼层嵌套与时间）
• 分批执行：每次请求处理一批（文章 20 篇 / 评论 100 条），前端自动循环直至完成，大站点不怕超时
• 断点续迁：映射表（wp2zs_map）记录 WP ↔ ZS 对象对应关系与迁移游标，中断后再次点击「开始迁移」自动续跑，重复执行不产生重复数据
• 域名替换：可配置旧域名 → 新域名替换，文章/评论中的图片与链接指向新站点
• 内容清洗：自动去除 Gutenberg 块注释（<!-- wp:... -->）、处理 caption/gallery 等常用短代码
• 进度可视：后台迁移控制台实时显示各对象「已迁移 / WP 总量」进度条与迁移日志
• 零侵入：不修改任何宿主文件，只读 WP 数据库（建议使用只读账号）

二、环境要求

三、快速开始

1. 将 WordPressToZsadmin 目录放入 plugins/，后台 应用中心 → WP转ZS → 安装
2. 确保 社区插件已安装（文章数据落到社区表）
3. 到 应用中心 → WP转ZS → 配置 填写 WP 数据库信息并保存：

  - 数据库地址 / 端口 / 库名 / 用户名 / 密码 / 表前缀（默认 wp，见 WP 站点 wp-config.php 中的 $tableprefix）

  - 建议为迁移创建只读账号，迁移完成后删除

1. 进入后台菜单 WP转ZS → 迁移控制台：

  - 点「测试连接」，确认能读到 WP 数据统计

  - 点「开始迁移」，自动按 分类 → 页面 → 文章 → 评论 顺序分批执行

1. 迁移完成后检查社区前台内容展示；如有图片，将 WP 的 wp-content/uploads 搬到新站点或配置域名替换

四、配置项说明

五、迁移规则

• 只迁移：poststatus=publish 的文章与页面、commentapproved=1 的评论、全部分类
• 评论归属：评论所属文章未迁移（草稿/回收站）时自动跳过该评论
• 楼层关系：WP 评论的父级若已迁移，会正确挂到对应评论之下（parent_id）
• 作者：文章与评论作者以配置的「作者显示名」展示（user_id=0，不影响现有用户体系）；留空则展示 WP 原作者名
• 正文：保留 HTML（去 Gutenberg 注释、短代码清洗）；WP 的 postexcerpt 作为页面 SEO 描述；页面 slug 取 WP postname（非法字符转 -）
• 时间：保留 WP 原始发布/评论时间
• 域名替换：同时替换 https:// 与 http:// 两种形式的旧域名

六、迁移控制台功能

• 测试连接：直连 WP 数据库并返回 文章/页面/评论/分类/用户 数量统计（表缺失会提示）
• 开始迁移：按 分类 → 页面 → 文章 → 评论 顺序自动分批执行，日志实时滚动；中断后可再次点击续跑
• 重置迁移：清空映射与游标（不会删除已导入的内容），用于从头重新迁移

七、常见问题

Q：测试连接失败？

依次检查：① 数据库地址/端口/库名/用户名/密码是否正确；② 本服务器能否访问 WP 数据库（远程库需放行 3306 或走内网）；③ 表前缀是否与 WP 站点一致。

Q：点「开始迁移」后某个步骤一直不动或反复重试？

查看控制台日志中的错误信息（如字段超长、编码异常）。修正后再次点击「开始迁移」即可从断点继续，已成功的对象不会重复导入。

Q：迁移后图片不显示？

WP 图片默认指向旧域名。两种方案：① 在配置中填写旧/新域名成对替换，并将 WP 的 wp-content/uploads 搬到新站点相同路径；② 迁移后手动批量替换数据库中的图片地址。

Q：分类下没有文章？

WP 文章按「第一个分类」归属；若该分类晚于文章迁移（不可能，步骤顺序保证分类先跑），或文章本身无分类，则归到「未分类」。可迁移后在后台调整。

Q：可以重复迁移吗？

可以。映射表去重 + 游标推进，重复执行只处理新增对象；「重置迁移」后才会从头再跑一遍（并可能与已导入内容重复，请先确认）。

Q：卸载会删除数据吗？

卸载仅清理后台菜单与映射表记录（表结构保留）；已迁移到社区表的文章、评论、页面不会删除，请通过社区插件后台自行管理。