摘要:面向 WordPress 开发者的版本技术说明。1.0.7 主要解决了「从物理文件模式切回虚拟输出后,站点根遗留旧文件压制新内容」这一类静默故障,同时梳理了插件在输出、生成、失败处理、字符清洗上的技术实现。
版本信息
表格
| 项 | 内容 |
|---|---|
| 版本号 | 1.0.7 |
| 依赖环境 | WordPress 6.5+ / PHP 7.4+ |
| 输出文件 | robots.txt、llms.txt(可选 llms-full.txt) |
| 数据存储 | 单个 option,不建数据表 |
| 前台资源 | 零 JS / 零 CSS,仅纯文本输出 |
| 后台菜单 | 「GEO 优化」顶层菜单,含概览 /robots.txt/llms.txt/ AI 爬虫 / 设置五个子页 |
一、1.0.7 修的是什么问题
先说这次的核心改动:从 file 或 both 模式切回 virtual 时,自动删除站点根遗留的旧物理文件。
这个问题的成因值得说清楚,因为它是典型的「配置改了、行为没变」型故障,排查成本很高。
插件的输出方式有三种:virtual、file、both。其中 virtual 模式的实现方式是挂 template_redirect 阶段直接输出纯文本响应,不落盘;file 模式是把内容写到站点根,由 Web 服务器直接返回静态文件。
问题出在模式切换上。Web 服务器的请求处理顺序决定了:站点根存在物理文件时,Nginx/Apache 会在进入 PHP 之前就把静态文件返回了,WordPress 根本没有被命中,template_redirect 上的钩子自然不会执行。
于是用户改了设置、点了保存、刷新页面,看到的还是旧内容。看起来像是「保存不生效」,实际是请求根本没走到插件。
1.0.7 的处理是在模式切换时主动清理:检测到目标是 virtual,且站点根存在此前生成的 robots.txt / llms.txt 物理文件,就删除它。这样请求才能重新落到 PHP 侧,虚拟输出才会真正生效。
同时保留了一个安全边界:删除只针对插件自己写入的文件,且在删除前确认文件内容特征,避免误删站点上其他人手写的同名文件。
二、生成链路的技术实现
llms.txt 的生成不是套模板,是扫库出稿,链路大致如下。
触发源有三类:手动触发(后台「重新生成」按钮)、内容变更触发(文章 / 页面 / 产品 / 服务的发布、更新、删除、状态流转、分类变更)、定时触发(WP-Cron,可选每小时或每天,默认每天)。
并发控制:内容变更触发走的是 save_post / transition_post_status 这类钩子,批量发布、批量改分类时会连续触发几十次。插件做了防抖处理,一个批次内只执行一次生成,避免反复扫描全表。这一点在导入大量文章时差别很明显,没做防抖的话生成时间会线性叠加,甚至把 PHP 进程打满。
内容组织:固定页面、分类归档、产品分组、服务类目、最新文章 / 产品 / 服务各自成区块。条目描述按固定优先级取:SEO 描述字段 → 摘要 → 产品 / 服务简介 → 正文截取。
这里有个设计取向:描述与页面 meta description 同源同序。同一个内容源、同一套截断规则,保证搜索引擎抓到的描述和 AI 读到的描述是同一份文本,不会出现两套口径。
内容来源可配:页面、文章、产品、服务、分类法分别可开关,各自设条数上限,避免内容量大的站点生成出几万行的 llms.txt。
全文版:开启后额外输出 llms-full.txt,带正文级别内容,用于需要全文的 RAG 场景。主文件和全文版分离,是因为索引型抓取和全文抓取对体积的容忍度完全不同。
三、失败路径的处理
生成类插件最容易被忽略的是失败路径。1.0.7 的处理原则是:生成失败不覆盖旧内容。
具体行为是:新内容生成后先做校验,通过才替换当前生效的内容;校验不通过或写入异常,保留上一次可用版本,把错误写入后台概览页的「最近错误」卡片。常见原因是目录权限不足。
另一种保护在物理文件模式上:写入前先备份到 wp-content/uploads/kuaigouzao-robots-llms-backups/,保留最近 20 份,出问题可回滚。这个备份目录不受卸载清理影响,需要清就手动删。
对 robots.txt 这种文件来说,这个设计不算多余。一个空的或损坏的 robots.txt 会被爬虫当成「全部允许」处理,等于把整站放开,副作用是持续的、不容易被发现的。
四、纯文本输出的字符清洗
robots.txt 和 llms.txt 是给机器读的,不是给人看的网页。所以输出前有一层专项清洗,处理两类问题:
一是 HTML 实体污染。内容从数据库取出时如果经过 the_content 之类的过滤器,可能带上 ’、& 这类实体编码,AI 读到的是转义串而不是文本,理解质量会下降。
二是内容逃逸。区块标题、条目描述如果直接拼接而不做边界处理,含换行或特殊字符的内容会破坏 llms.txt 的 Markdown 结构,导致后面的区块解析失败。
清洗规则是白名单式:保留符合纯文本语义的字符,不符合的一律归一或剔除。
五、输出模式的取舍
三种模式的技术差异,建议按场景选:
表格
| 模式 | 实现 | 适用 | 注意 |
|---|---|---|---|
virtual |
template_redirect 直接输出响应,自带 Content-Type: text/plain; charset=utf-8 |
绝大多数站点;站点根不可写;需要正确 charset 声明 | 需确保没有其他规则在更早阶段拦截 |
file |
写入站点根,由 Web 服务器返回 | 需要被 CDN 或访问日志直接处理的场景 | 修改后需清缓存;编码由服务器配置决定 |
both |
两者兼有 | 特殊兼容需求 | 服务器优先返回物理文件,改设置后看到旧内容属预期行为 |
virtual 模式的一个附带好处是编码声明。file 模式下 Nginx 返回静态 .txt 时如果没有 charset utf-8;,浏览器按默认编码解析就会出现乱码。虚拟输出由 PHP 直接带上 charset,从源头规避。若必须用物理文件,在站点配置里补一行即可:
charset utf-8;
另外 virtual 模式下 robots.txt 和 llms.txt 各自独立配置,可以一个用虚拟、一个用物理,互不影响。
六、爬虫 UA 库的分组逻辑
内置 UA 库按三组划分,默认策略为「AI 助手放行 / AI 训练拦截 / 其它放行」。
这个默认值的依据是两类抓取的用途不同:AI 助手类(ChatGPT-User、OAI-SearchBot、Claude-User、PerplexityBot 等)是用户主动提问时触发抓取,抓取结果用于当次回答或搜索索引,放行意味着可能被引用并带来流量;AI 训练类(GPTBot、ClaudeBot、Bytespider、Google-Extended 等)是抓全站喂模型,放行等于无偿提供训练语料。
robots 的规则合并有几处容易出错:多个 User-agent 段的匹配顺序、专有段与 * 通配段的覆盖关系、Allow 与 Disallow 同路径时的优先级。插件把顺序固定为「专有 UA 段在前、通配段在后」,并在合并时做路径长度优先判断,避免手写时常见的互相压制。