Claude Code 开发 WordPress 插件完整教程

用 Claude Code 开发 WordPress 插件，最适合的方式不是直接说“帮我写一个插件”，而是把插件开发拆成需求、骨架、核心功能、安全处理、测试和打包几个阶段。Claude Code 可以帮你生成文件、理解 WordPress Hooks、补设置页、写短代码、检查安全问题，但每一步都需要开发者确认范围和代码质量。

本文会从零讲清 Claude Code 开发 WordPress 插件的完整流程。还没配置 Claude Code 或本地 WordPress 环境的读者，可以先看本站 安装部署教程 和 环境配置教程；想把插件开发流程沉淀成日常 AI 编程 SOP，可以继续阅读 实战工作流。

摘要

使用 Claude Code 开发 WordPress 插件，推荐流程是：先把插件需求写成明确规格，说明功能边界、后台菜单、前台输出、用户权限、数据存储方式和不做什么；再让 Claude Code 生成插件骨架，包括主插件文件、插件头注释、includes、assets、templates 等目录；接着围绕 WordPress action、filter、activation hook、settings API、shortcode 或 block 功能逐步实现；每个阶段都要求 Claude Code 先给计划，再修改文件；代码完成后检查 nonce、capability、sanitize、escape、ABSPATH、卸载清理和资源加载；最后在本地 WordPress 环境激活插件、测试后台设置、前台输出、禁用卸载和 zip 打包。插件开发可以由 AI 加速，但安全、兼容和发布前审查必须人工完成。

正文

先明确插件需求

WordPress 插件开发最怕需求不清。你需要先告诉 Claude Code 这个插件解决什么问题、面向谁、后台是否需要设置页、前台如何输出、是否需要短代码、是否写入数据库、是否要加载 JS/CSS、哪些功能暂时不做。

我要开发一个 WordPress 插件。
功能：在文章末尾自动显示一个自定义 CTA 区块。
后台：需要设置 CTA 标题、按钮文字、按钮链接。
前台：只在单篇文章页显示。
权限：只有 manage_options 用户可以修改设置。
限制：不要创建自定义数据表，不要引入前端构建工具，先做轻量版本。

需求越具体，Claude Code 生成的插件结构越稳定。

第一步：让 Claude Code 生成插件骨架

WordPress 官方插件手册说明，最简单的插件是一个带有插件头注释的 PHP 文件。实际开发中，建议从一开始就建立清晰目录，避免所有代码堆在一个文件里。

请为这个插件生成基础骨架，但先给计划，等我确认后再写文件。
目录建议：
- my-cta-plugin.php 主插件文件
- includes/class-admin.php 后台设置
- includes/class-frontend.php 前台输出
- assets/css/frontend.css 前台样式
- uninstall.php 卸载清理
要求：包含插件头、ABSPATH 防直接访问、基础类加载。

第二步：确认主插件文件

主插件文件通常包含插件头、常量定义、文件加载和启动入口。不要让 Claude Code 一开始把所有逻辑写进主文件。主文件应该只负责“加载”和“启动”。

<?php
/**
 * Plugin Name: My CTA Plugin
 * Description: Adds a custom CTA block after single post content.
 * Version: 1.0.0
 * Author: Your Name
 */

if (!defined('ABSPATH')) {
    exit;
}

实际代码可以由 Claude Code 生成，但你要检查插件头是否完整、命名是否唯一、常量是否带前缀，避免和其他插件冲突。

第三步：用 Hooks 接入 WordPress

WordPress 插件开发离不开 hooks。官方文档把 hooks 分为 actions 和 filters：action 用于在特定阶段执行逻辑，filter 用于修改某个值。常见场景包括 admin_menu 添加后台菜单、admin_init 注册设置、wp_enqueue_scripts 加载资源、the_content 修改文章内容。

请实现前台输出逻辑：
1. 使用 the_content filter
2. 只在 is_singular('post') 且主查询中追加 CTA
3. CTA 内容来自 options
4. 输出前做好 esc_html、esc_url
5. 不影响后台和归档页

第四步：实现后台设置页

如果插件需要后台配置，必须处理权限、nonce、数据清洗和输出转义。让 Claude Code 写设置页时，要明确使用 manage_options 权限，保存前 sanitize，输出时 escape。

请实现后台设置页：
- 菜单放在 Settings 下
- 权限使用 manage_options
- 字段：标题、按钮文字、按钮链接
- 保存时 sanitize_text_field 和 esc_url_raw
- 输出时 esc_html 和 esc_url
- 使用 WordPress Settings API

不要让设置页直接信任 $_POST，也不要把未清洗的数据直接输出到前台。

第五步：添加激活、停用和卸载逻辑

WordPress 官方文档提供 register_activation_hook、register_deactivation_hook 和 uninstall 机制。激活时适合设置默认选项、刷新重写规则；停用时一般不要删除用户数据；卸载时才清理插件创建的选项或数据。

请添加插件生命周期逻辑：
1. activation 时写入默认 option
2. deactivation 不删除用户设置
3. uninstall.php 中删除本插件 option
4. 不要删除其他插件或主题数据

第六步：实现短代码或区块

如果插件需要用户手动插入内容，可以先从 shortcode 做起。短代码简单、兼容性好，不需要复杂构建流程。等功能稳定后，再考虑区块编辑器 Block。

请新增 shortcode [my_cta]：
- 支持 title、button_text、url 参数
- 默认值来自插件设置
- 输出 HTML 前做好转义
- 不加载多余脚本
- 给出使用示例

第七步：加载 CSS 和 JS

资源加载不要直接在模板里写 link 或 script。前台资源用 wp_enqueue_scripts，后台资源用 admin_enqueue_scripts，并尽量只在需要的页面加载。

请添加前台 CSS 加载：
1. 使用 wp_enqueue_scripts
2. 只在单篇文章页或 shortcode 存在时加载
3. 使用 plugins_url 定位 assets/css/frontend.css
4. 设置版本号，便于缓存刷新

第八步：做安全检查

插件开发一定要检查安全细节。重点包括：防止直接访问 PHP 文件、后台操作校验 capability、表单使用 nonce、保存数据 sanitize、输出数据 escape、数据库查询使用 prepare、AJAX 请求校验权限。

请审查插件安全性：
1. 是否所有 PHP 文件都有 ABSPATH 检查
2. 后台保存是否校验 nonce 和 capability
3. 输入是否 sanitize
4. 输出是否 escape
5. URL 是否使用 esc_url
6. 是否存在未授权 AJAX 或 REST 操作
7. 是否误删用户数据

第九步：本地测试插件

把插件复制到 wp-content/plugins 目录后，在后台启用。测试时至少覆盖：插件能否激活、设置页是否保存成功、前台是否按条件显示、短代码是否正常、禁用后是否不再输出、卸载是否清理本插件数据。

wp-content/plugins/my-cta-plugin/
  my-cta-plugin.php
  includes/
  assets/
  uninstall.php

如果使用 WP-CLI，可以让 Claude Code 帮你生成测试命令，但执行前仍要确认不会影响线上站点。

第十步：让 Claude Code 生成测试清单

插件开发完成后，不要只看能不能激活。让 Claude Code 输出测试清单：

请为这个 WordPress 插件生成发布前测试清单：
1. 激活和停用
2. 设置页保存
3. 前台显示条件
4. shortcode 输出
5. CSS 加载
6. 权限和 nonce
7. 输入清洗和输出转义
8. 卸载清理
9. 与常见主题兼容
10. zip 打包检查

第十一步：打包插件

打包前检查目录结构，不要把 node_modules、.git、临时日志、测试截图、真实密钥、数据库备份打进 zip。readme.txt、截图、版本号、最低 WordPress/PHP 要求也要确认。

my-cta-plugin.zip
└── my-cta-plugin/
    ├── my-cta-plugin.php
    ├── includes/
    ├── assets/
    ├── uninstall.php
    └── readme.txt

第十二步：完整提示词模板

下面这段可以直接复制给 Claude Code：

请帮我开发一个 WordPress 插件。
当前阶段先给计划，不要立即写文件。

插件需求：
【写清插件功能】

后台设置：
【是否需要菜单、字段、权限】

前台输出：
【自动追加、shortcode、block 或 widget】

限制：
- 不创建自定义数据表，除非我确认
- 不引入前端构建工具
- 不修改主题文件
- 不访问真实密钥
- 所有输入 sanitize，所有输出 escape

请先输出：
1. 插件目录结构
2. 主插件文件职责
3. 使用哪些 action/filter
4. 设置页实现方式
5. 安全检查点
6. 测试和打包计划
等我确认后再生成文件。

开发时不要做的事

不要让 Claude Code 修改主题核心文件，不要在插件里硬编码管理员账号密码，不要直接删除线上文章或选项，不要把密钥写进插件源码，不要跳过 nonce 和 capability 检查。更多安全和排错思路，可以查看本站 问题排查教程。

FAQ

Claude Code 能直接生成完整 WordPress 插件吗？

可以生成初版，但不建议一次性完成全部功能。更稳妥的做法是先生成骨架，再逐步实现后台设置、前台输出、安全检查和测试。

插件开发必须会 PHP 吗？

最好具备基础 PHP 和 WordPress Hooks 概念。Claude Code 可以加速开发，但你仍然需要审查权限、安全、数据清洗和输出转义。

短代码和区块应该先做哪个？

新手建议先做 shortcode，结构简单、兼容性好。等功能稳定后，再考虑开发区块编辑器 Block。

Claude Code 写的插件怎么测试？

在本地 WordPress 环境安装启用，测试激活、设置页保存、前台输出、短代码、资源加载、停用和卸载。不要直接在生产站点测试新插件。

插件可以直接上传到线上吗？

不建议。应先在本地或测试站验证，通过安全检查和兼容性测试后，再打包上传线上。上线前务必备份站点。