给 WordPress 插件加后台设置页面,通常是在插件主文件或由主文件引入的 admin 文件中,用 admin_menu 钩子注册页面,再通过 Settings API 或自建表单处理保存。若插件还没有选项存储结构,建议先把页面位置、权限、字段和保存回调拆开;如果插件已经有一套设置框架或使用自定义表,先沿用现有结构,不要为了加一个页面另起一套存储。
适用场景:插件需要一个可保存的后台选项页,且当前没有现成设置入口。操作上先确认入口放在 Settings 下还是独立菜单、谁有权限修改、选项是否已有存储方式;再用 add_options_page() 注册页面,用 register_setting() 和 settings_fields() 处理保存。验证时看菜单是否出现、保存后刷新是否保留、无权限账号是否看不到;若插件已有自定义表或权限模型,不宜直接套本示例,应先复用现有方案。
先确认当前场景和目标
先判断三件事:设置入口放在哪里、保存到哪里、谁能改。普通单站点插件常把入口放在 Settings 菜单下,使用 options 表存数组;如果插件功能较多,也可以注册独立顶级菜单。权限通常用 manage_options,但面向编辑或订阅者的设置需要换 capability,并确认后台菜单和保存回调都做同样判断。
还要确认插件是否已有设置页面或选项名。如果已有 register_setting() 调用,继续用原来的 group 和 option 名;如果是自定义表,Settings API 的 options.php 提交流程就不一定合适。多站点环境还要判断是站点级设置还是网络级设置,网络级通常要改用 network_admin_menu 和网络选项。
按这个顺序处理
第一步先注册菜单。把下面片段放在插件主文件或只在后台加载的文件里;页面 slug、菜单标题和回调函数名按自己的插件替换。add_options_page() 的第四个参数是页面 slug,后面 settings_fields() 和 do_settings_sections() 要与它对应。
add_action('admin_menu', 'example_plugin_add_settings_page');
function example_plugin_add_settings_page() {
add_options_page(
'示例插件设置',
'示例插件',
'manage_options',
'example-plugin-settings',
'example_plugin_render_settings_page'
);
}
第二步注册字段和保存规则。下面用 Settings API 的常见做法:register_setting() 指定 group 和 option 名,add_settings_section() 与 add_settings_field() 生成字段。sanitize_callback 必须做字段清洗,否则保存时容易把未过滤内容写进 options。

add_action('admin_init', 'example_plugin_register_settings');
function example_plugin_register_settings() {
register_setting('example_plugin_group', 'example_plugin_options', [
'type' => 'array',
'sanitize_callback' => 'example_plugin_sanitize_options',
'default' => ['api_key' => '', 'enabled' => 0],
]);
add_settings_section(
'example_plugin_main',
'基础设置',
'__return_false',
'example-plugin-settings'
);
add_settings_field(
'example_plugin_api_key',
'API Key',
'example_plugin_render_api_key_field',
'example-plugin-settings',
'example_plugin_main'
);
}
function example_plugin_render_api_key_field() {
$options = get_option('example_plugin_options', []);
$value = isset($options['api_key']) ? $options['api_key'] : '';
$value = esc_attr($value);
echo <<<HTML
<input type='text' name='example_plugin_options[api_key]' value='$value' class='regular-text' />
HTML;
}
function example_plugin_sanitize_options($input) {
return [
'api_key' => isset($input['api_key']) ? sanitize_text_field($input['api_key']) : '',
'enabled' => empty($input['enabled']) ? 0 : 1,
];
}
第三步写页面渲染回调。表单 action 指向 options.php,settings_fields() 输出 nonce 和 group 隐藏字段,do_settings_sections() 输出已注册字段,submit_button() 生成提交按钮。页面内再检查一次 current_user_can(),不要只依赖菜单是否显示。
function example_plugin_render_settings_page() {
if ( ! current_user_can('manage_options') ) {
return;
}
?>
<div class=wrap>
<h1>示例插件设置</h1>
<form method=post action=options.php>
<?php settings_fields('example_plugin_group'); ?>
<?php do_settings_sections('example-plugin-settings'); ?>
<?php submit_button(); ?>
</form>
</div>
<?php
}
如果设置必须写入自定义表而不适合 options 表,就不要硬套 options.php:改用 admin_post_ 动作接收表单,先 check_admin_referer() 校验 nonce,再检查 capability,最后用 $wpdb->update() 或 $wpdb->insert() 并配合 prepare() 写库。
改完后怎么验证
启用插件后进入后台,先看 Settings 菜单下是否出现插件入口,再打开页面确认字段和提交按钮都在。修改一个可识别值后保存,观察页面是否出现保存提示;刷新页面,确认输入框仍显示刚才的值。这个动作能同时验证菜单注册、group 对应和保存回调是否接通。
再用一个没有 manage_options 权限的账号访问该页面地址,预期是看不到菜单或进入后被拒绝;如果仍能看到表单,要回头检查 add_options_page() 的 capability 参数和渲染回调里的 current_user_can()。最后在插件前台逻辑或临时调试代码里读取 get_option('example_plugin_options'),确认后台保存的值与前台读取一致;调试输出不要长期留在正式页面。

如果保存后值没有保留,优先核对 settings_fields() 的 group 是否与 register_setting() 的 group 完全一致,页面 slug 是否与 do_settings_sections() 一致,以及 option 名是否在读取时写错。也可以用 WP-CLI 的 wp option get example_plugin_options 辅助查看,前提是环境已安装并可用 WP-CLI。
容易忽略的边界
权限边界要成对处理:菜单注册、页面渲染、保存回调三处都应使用同一套 capability 判断。只隐藏菜单不阻止直接访问,不能算权限控制。需要让编辑角色修改设置时,建议明确改成 edit_posts 或其他合适能力,并确认这个角色不会因此获得其他后台入口。
多站点环境要单独判断:站点级设置用 admin_menu 和普通 options;网络级设置通常要换 network_admin_menu,并操作网络选项或自定义表。版本差异方面,后台菜单和 Settings API 的用法长期稳定,但字段类型、默认值和 sanitize 回调的实现需要结合当前 WordPress 环境确认,不要假设某个旧版本行为完全一致。
不适用或应回退的情况:插件已有自定义设置框架、使用自定义表、或者设置项需要复杂权限分组时,不建议再新增一套平行的 options.php 表单;应复用现有保存入口,或把新页面做成现有框架下的一个子页面。若页面注册后出现白屏,先检查回调函数名是否拼错、是否在未加载的 admin 文件中定义,以及 add_options_page() 的返回页是否与 settings_fields() 的 group 对应。