WordPress插件如何通过指定PHP文件添加后台顶级菜单入口

问题原因与修复方案 #

1. 菜单钩子挂载逻辑错误 #

你将admin_menu动作的注册代码放在了插件激活钩子中，register_activation_hook仅会在插件首次激活时执行一次，后续访问WordPress后台时不会触发菜单注册逻辑，自然无法显示菜单。
你需要将菜单注册钩子移出激活钩子，改为全局挂载，激活钩子仅保留插件激活时的初始化逻辑（如创建数据表、写入默认配置等）。

2. 菜单回调参数使用错误 #

add_menu_page的第五个参数仅支持可调用的回调类型（函数名、类方法数组、匿名函数），不能直接传入PHP文件路径或者非法的调用格式。你只需要在自定义回调函数中引入你的设置页PHP文件即可实现渲染。

修正后的完整代码 #

第一步：修正钩子注册逻辑（插件主文件内） #

// 先定义插件物理路径常量，用于后续文件引入，注意不要用URL引入本地文件
define( 'SWTC_PATH', plugin_dir_path( __FILE__ ) );

// 菜单注册钩子全局挂载，不要放在激活钩子内
add_action( 'admin_menu', 'stwc_add_menu_entry' );

// 激活钩子仅保留激活时的初始化逻辑
register_activation_hook( __FILE__, 'stwc_activation' );
function stwc_activation(){
    // 此处填写插件激活时需要执行的逻辑，比如创建自定义表、写入默认设置等
}

第二步：修正菜单注册与页面渲染逻辑 #

function stwc_add_menu_entry() {
    add_menu_page(
        'stwc',
        'stwc Options',
        'manage_options',
        'stwc', // 此处为菜单别名，填唯一的字符串即可，不要写文件路径
        'stwc_render_settings_page', // 填写自定义回调函数名
        SWTC_URL . 'admin/images/swtc-icon.png',
        20
    );
}

// 回调函数内引入你的设置页文件完成渲染
function stwc_render_settings_page() {
    // 校验文件存在后引入，避免报错
    if ( file_exists( SWTC_PATH . 'includes/stwc_settings.php' ) ) {
        require_once SWTC_PATH . 'includes/stwc_settings.php';
    }
}

额外注意事项 #

• 引入本地PHP文件必须使用服务器物理路径，不能使用HTTP URL，所以要提前定义SWTC_PATH这类路径常量，不要误用之前的SWTC_URL常量引入文件。
• add_menu_page第四个参数为菜单的唯一别名，仅用于后台URL标识，不要填写文件路径。

内容的提问来源于stack exchange，提问作者Jason 'Slingshot' Miller