1. 从零写一个 WordPress 插件add_action 挂载 admin_menu 到底解决了什么问题如果你刚接触 WordPress 插件开发最容易卡住的地方不是 PHP 语法而是「我写的函数为什么后台看不到」。WordPress 的插件机制本质是一套钩子Hook系统你的代码不会自动执行必须通过add_action或add_filter把自己挂到 WordPress 的运行流程上。管理页面尤其典型后台左侧菜单是 WordPress 在admin_menu这个时机统一渲染的你只有在这个时机之前把注册函数挂上去菜单项才会出现。这篇要做的插件目标很明确在后台侧边栏加一个顶级菜单点进去是一个设置表单表单里填 API Key 和模型 ID保存后插件用这些配置去请求 TaoToken 的统一 API 通道。这样你以后写任何需要调用大模型的 WordPress 插件都能复用这套「管理页 配置存储 请求转发」的骨架。适合谁看会一点 PHP、能进 WordPress 后台、想给自己的站点加 AI 能力但不想把 Key 硬编码在主题里的开发者。整篇按「目录结构 → 挂载菜单 → 渲染表单 → 保存配置 → 发请求 → 排错」的顺序走每一步都给可复制的代码。先说清楚一个概念避免后面混淆。add_action(admin_menu, callback)里的admin_menu是一个动作钩子它在 WordPress 准备构建后台菜单时触发。你的callback函数里再调用add_menu_page()才算真正把页面注册进去。很多人只写了add_menu_page却忘了外面包一层add_action结果页面死活不显示这是新手第一大坑。TaoToken 在这里的角色是「统一 Key/API 通道」。你不需要在插件里分别对接各家模型的地址和鉴权格式把 Base URL 指向https://taotoken.net/api用同一个 Key 就能切换模型。对插件来说配置项少了一个数量级维护成本也低。下面进入实操。2. 插件目录结构与 TaoToken 前置准备add_action 注册管理页 TVA 长尾检索词2.1 目录结构怎么放WordPress 只会扫描wp-content/plugins/下的目录和 PHP 文件来识别插件。推荐一个插件一个子目录主文件带头部注释。结构如下wp-content/plugins/ └── taotoken-admin-demo/ ├── taotoken-admin-demo.php // 插件入口含头部注释 ├── includes/ │ ├── menu.php // add_action add_menu_page │ └── settings.php // 表单渲染与保存 └── assets/ └── admin.css // 可选后台样式入口文件taotoken-admin-demo.php的头部注释是 WordPress 识别插件的唯一凭据Plugin Name必须有?php /** * Plugin Name: TaoToken Admin Demo * Description: 演示用 add_action 挂载 admin_menu注册管理页面并接入 TaoToken API。 * Version: 0.1 * Author: Your Name */ if ( ! defined( ABSPATH ) ) { exit; // 防止直接访问 } require_once plugin_dir_path( __FILE__ ) . includes/menu.php; require_once plugin_dir_path( __FILE__ ) . includes/settings.php;ABSPATH判断是安全习惯防止有人直接请求这个 PHP 文件绕过 WordPress。plugin_dir_path(__FILE__)返回当前文件所在目录的绝对路径用它拼includes/下的文件最稳。2.2 TaoToken 前置拿 Key、确认 Base URL在写请求代码之前先把通道准备好。打开https://taotoken.net/api-keys创建一个 API Key复制保存。然后在文档页https://taotoken.net/doc确认两件事Base URL 是https://taotoken.net/api以及你要用的模型 ID比如对话类模型的标识。这两项后面会填进插件的设置表单。这里有个设计取舍值得说。为什么不把 Key 直接写在 PHP 里因为插件代码可能被备份、被同步到 Git、被多人查看硬编码等于泄露。正确做法是存进 WordPress 的 options 表通过get_option()读取。TaoToken 的 Key 一旦泄露别人可以消耗你的额度所以务必走后台配置。2.3 用 add_action 挂载 admin_menuincludes/menu.php的核心就是两件事挂钩子、注册页面。?php add_action( admin_menu, taotoken_demo_setup_menu ); function taotoken_demo_setup_menu() { add_menu_page( TaoToken 设置, // 页面 title TaoToken, // 菜单显示文字 manage_options, // 所需权限 taotoken-demo, // 菜单 slug taotoken_demo_render_page,// 渲染回调 dashicons-admin-generic, // 图标 80 // 位置 ); }逐个参数解释。第一个是浏览器标签和页面标题用的第二个是左侧菜单看到的文字manage_options是权限门槛只有管理员能看到普通订阅者看不到taotoken-demo是 slug会出现在 URL 的?pagetaotoken-demo里渲染回调指向settings.php里的函数图标用 WordPress 内置的 dashicons位置 80 让它排在设置菜单附近。注意add_action的第二个参数是函数名字符串不是函数调用。写成taotoken_demo_setup_menu()加括号就错了那会立即执行并把返回值当回调通常返回 null菜单自然不出现。这个细节我在早期踩过排查了半天。3. 可复制配置渲染设置表单并保存到 options 表3.1 渲染页面与表单includes/settings.php负责输出 HTML 和处理保存。先看渲染?php function taotoken_demo_render_page() { if ( ! current_user_can( manage_options ) ) { return; } $api_key get_option( taotoken_api_key, ); $base_url get_option( taotoken_base_url, https://taotoken.net/api ); $model_id get_option( taotoken_model_id, ); ? div classwrap h1TaoToken 设置/h1 form methodpost actionoptions.php ?php settings_fields( taotoken_demo_group ); ? table classform-table tr thlabel fortaotoken_api_keyAPI Key/label/th tdinput typepassword idtaotoken_api_key nametaotoken_api_key value?php echo esc_attr( $api_key ); ? classregular-text //td /tr tr thlabel fortaotoken_base_urlBase URL/label/th tdinput typetext idtaotoken_base_url nametaotoken_base_url value?php echo esc_attr( $base_url ); ? classregular-text //td /tr tr thlabel fortaotoken_model_idModel ID/label/th tdinput typetext idtaotoken_model_id nametaotoken_model_id value?php echo esc_attr( $model_id ); ? classregular-text //td /tr /table ?php submit_button(); ? /form /div ?php }current_user_can再校验一次权限双保险。get_option的第二个参数是默认值Base URL 默认就填 TaoToken 的地址用户不用记。esc_attr转义输出防止 XSS。settings_fields输出 nonce 和 action 隐藏字段这是 WordPress 设置 API 的安全机制。3.2 注册设置项光有表单不够得告诉 WordPress 哪些字段可以保存。在settings.php里加add_action( admin_init, taotoken_demo_register_settings ); function taotoken_demo_register_settings() { register_setting( taotoken_demo_group, taotoken_api_key, array( type string, sanitize_callback sanitize_text_field, ) ); register_setting( taotoken_demo_group, taotoken_base_url, array( type string, sanitize_callback esc_url_raw, ) ); register_setting( taotoken_demo_group, taotoken_model_id, array( type string, sanitize_callback sanitize_text_field, ) ); }admin_init在每次后台初始化时触发适合注册设置。sanitize_callback是清洗函数Key 和模型 ID 用sanitize_text_field去掉多余标签URL 用esc_url_raw保证是合法地址。表单提交到options.php后WordPress 会自动调用这些清洗函数再写库。3.3 用 wp_remote_post 请求 TaoToken配置存好后写一个请求函数放在settings.php末尾function taotoken_demo_call_api( $prompt ) { $api_key get_option( taotoken_api_key, ); $base_url get_option( taotoken_base_url, https://taotoken.net/api ); $model_id get_option( taotoken_model_id, ); if ( empty( $api_key ) || empty( $model_id ) ) { return new WP_Error( missing_config, 请先在后台填写 API Key 和 Model ID ); } $response wp_remote_post( trailingslashit( $base_url ) . v1/chat/completions, array( timeout 30, headers array( Authorization Bearer . $api_key, Content-Type application/json, ), body wp_json_encode( array( model $model_id, messages array( array( role user, content $prompt ), ), ) ), ) ); if ( is_wp_error( $response ) ) { return $response; } $code wp_remote_retrieve_response_code( $response ); $body wp_remote_retrieve_body( $response ); if ( 200 ! $code ) { return new WP_Error( api_error, HTTP . $code . : . $body ); } return json_decode( $body, true ); }wp_remote_post是 WordPress 封装的 HTTP 客户端比裸curl更兼容不同主机环境。trailingslashit保证 Base URL 末尾有斜杠再拼路径避免出现双斜杠或漏斜杠。鉴权用标准的Bearer头TaoToken 的通道兼容这种格式。返回体按 JSON 解析失败时用WP_Error传递方便上层判断。4. 验证请求与成功结果后台页面加载和 API 返回怎么确认4.1 确认菜单和页面加载把插件目录放进wp-content/plugins/进后台「插件」列表找到 TaoToken Admin Demo 点启用。启用后左侧应该出现 TaoToken 菜单。点进去URL 类似/wp-admin/admin.php?pagetaotoken-demo页面显示三个输入框和保存按钮。如果菜单没出现先看add_action是否写对再看权限是不是manage_options最后确认menu.php有没有被require_once引入。这三步能覆盖九成「菜单不显示」的问题。4.2 保存配置并验证写库填入从https://taotoken.net/api-keys拿到的 Key、Base URL 保持默认、Model ID 填你文档里确认的模型标识点保存。页面刷新后字段还在说明写库成功。想更确定可以在wp_options表里搜taotoken_api_key能看到记录。4.3 触发一次真实请求在settings.php里临时加一个测试入口或者用 WP-CLI 执行$result taotoken_demo_call_api( 用一句话介绍 WordPress 插件机制 ); if ( is_wp_error( $result ) ) { error_log( $result-get_error_message() ); } else { error_log( print_r( $result, true ) ); }成功时$result里会有choices数组第一项的message.content就是模型回复。看到这个结构说明从后台配置到 TaoToken 通道的整条链路通了。实测下来首次请求可能因为网络或额度问题稍慢timeout设 30 秒比较稳妥。4.4 参数对照表配置项存库键名默认值清洗函数API Keytaotoken_api_key空sanitize_text_fieldBase URLtaotoken_base_urlhttps://taotoken.net/apiesc_url_rawModel IDtaotoken_model_id空sanitize_text_field这张表建议对照自己的代码检查一遍键名写错会导致get_option读不到值表现为「保存了但请求说没配置」。5. 本篇常见错排查401、local proxy failed、reading choices 报错怎么定位5.1 HTTP 401 Unauthorized最常见。原因通常是 Key 没填、填错、或者Authorization头拼错。检查两点get_option(taotoken_api_key)是否真的返回了值请求头是不是Bearer . $api_key注意 Bearer 后面有一个空格。如果 Key 是从别处复制带上了换行sanitize_text_field会处理掉但手动拼接时容易漏。5.2 local proxy failed 类报错这类提示一般出现在本地开发环境说明请求根本没发出去被本地网络层拦了。先确认你的 WordPress 能正常访问外网再确认 Base URL 拼出来的完整地址是https://taotoken.net/api/v1/chat/completions。如果地址里出现了双斜杠或缺少v1服务端会返回 404 而不是这个错所以重点看网络连通性。5.3 reading choices 报错这个报错说明代码在解析返回体时choices字段不存在。原因通常是返回的不是成功结构而是错误 JSON比如{error: {...}}。排查方法在json_decode之前把$body打到日志里看原始内容。如果$code不是 200我的示例代码已经提前返回WP_Error了所以出现这个错多半是你自己改过逻辑把状态码判断去掉了。补回状态码检查即可。5.4 OAuth 相关报错如果你在插件里用了需要 OAuth 的第三方库可能看到 token 过期或 scope 不足的提示。TaoToken 的 API Key 通道不走 OAuth用的是 Bearer 鉴权所以这类报错一般来自你混用了其他服务的 SDK。确认请求只发往https://taotoken.net/api鉴权头只有Authorization: Bearer不要叠加其他认证方式。5.5 三件套检查清单无论哪种报错先核对这三件套是否齐全且一致Base URLhttps://taotoken.net/apiAPI Key从https://taotoken.net/api-keys获取Model ID从https://taotoken.net/doc确认三者缺一或写错请求都不会成功。把这三个值在后台表单里重新填一遍保存再触发请求多数问题能自愈。6. 把配置通道固定下来后续扩展与 TaoToken 接入入口到这里一个能跑通的管理页插件就完成了。它的价值不只是「显示一个页面」而是给你一套可复用的模式用add_action(admin_menu)挂菜单用 Settings API 存配置用wp_remote_post走 TaoToken 统一通道。以后你要加功能比如在文章编辑页加一个「AI 润色」按钮只需要复用taotoken_demo_call_api()把 prompt 换成文章内容即可Key 和地址都不用再动。如果你打算把这个骨架用在正式项目里建议再做两件事。一是把请求函数里的错误信息记到error_log方便线上排查二是给表单加一个「测试连接」按钮点击后发一条极短的请求把结果显示在页面上这样用户填完配置能立刻知道对不对。需要继续深入的话几个入口按用途分想直接验证模型返回效果去模型对话页https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite手动发一条消息看结构想管理或新建 Key去 API Keys 页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite想查接口参数和模型列表去文档页https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。如果你的插件后续要长期跑批量任务或 Agent 类逻辑可以了解 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite它在额度规划上更适合持续调用。最后留一个实操建议把taotoken_demo_call_api()的返回结构打印一次看清楚choices[0].message.content的层级再决定你的插件怎么消费这个结果。这一步做完你对整条链路的理解就从「能跑」变成「能改」了。