WordPress 用户角色与权限终极指南：从默认角色到自定义权限的完整实战

1. 开头导语

WordPress 自带的角色与权限系统（Roles & Capabilities）是整站安全的第一道闸门，也是站长最容易忽视的隐患。一个权限配错的角色，轻则让投稿者删掉编辑已发布的文章，重则让低权限用户拿到 manage_options 后植入后门、窃取数据库。Sucuri 历年的网站安全报告反复指出：超过 30% 的 WordPress 入侵事件与”过宽的权限配置”或”弱口令管理员账号”直接相关。

本教程将系统拆解 WordPress 权限体系：从六大默认角色和底层 WP_Roles / WP_Role / WP_User 三大类的运作机制讲起，到 current_user_can() 与 user_can() 的使用差异、自定义角色的三种创建方法、自定义文章类型（CPT）的 capability_type 与 map_meta_cap 映射、REST API 的 permission_callback、AJAX 与 nonce 验证、IDOR 漏洞防范，再到多站点网络的超级管理员体系、WooCommerce/bbPress/BuddyPress 的角色扩展，最后给出一份最佳实践清单和故障排查手册。无论你是独立站长还是给客户交付项目的开发者，本文都能帮你把权限这把”刀”磨得锋利而不伤手。

2. WordPress 用户角色系统基础

2.1 角色与权限的关系（Role vs Capability）

WordPress 的权限模型本质上是 RBAC（Role-Based Access Control，基于角色的访问控制） 的实现。理解它要先分清三个概念：

• Capability（能力）：系统中最细粒度的权限单位，例如 edit_posts、manage_options、upload_files。一个能力就对应”能否做某件具体的事”。
• Role（角色）：一组能力的集合，例如”编辑（Editor）”包含 edit_posts、edit_others_posts、publish_posts 等数十个能力。
• User（用户）：一个账号可以被分配一个或多个角色，从而间接获得这些角色所包含的能力。WordPress 核心默认每个用户只有一个主角色，但底层 WP_User 实际支持多角色。

判断权限时，WordPress 不会直接问”这个用户能不能编辑文章”，而是问”这个用户所属的角色是否包含 edit_posts 能力”。这种”用户→角色→能力”的三层结构，让你只需要管理角色，而不用为每个用户单独配置权限。

2.2 核心权限系统原理

WordPress 权限系统在底层由三个核心类支撑，全部位于 wp-includes/class-wp-*.php：

• WP_Roles：管理所有角色定义的”总管”类。它持有 $roles 数组，存放每个角色的名称、显示名和能力清单。WP_Roles 通过 get_option('wp_user_roles') 读取数据库中的角色序列化数据（多站点下是 wp_<site_id>_user_roles）。WP_Roles 是单例，全局通过 $wp_roles 访问。
• WP_Role：单个角色的封装类。每个 WP_Role 实例对应一个角色，提供 add_cap()、remove_cap()、has_cap() 方法。修改它的能力会同步写回 WP_Roles 并持久化到 wp_user_roles 选项。
• WP_User：单个用户类，持有 $caps（用户直接能力）和 $roles（所属角色）两个数组。WP_User::has_cap() 会先检查用户直接能力，再合并角色能力，最后由 map_meta_cap 过滤器做”动态能力映射”。

权限校验的完整调用链是：

current_user_can('edit_post', 99)
  → WP_User::has_cap('edit_post')
  → 检查角色中是否有 edit_posts / edit_others_posts 等基础能力
  → map_meta_cap 过滤器把 'edit_post' 映射为 ['edit_posts', 'edit_others_posts'] 等"原始能力"
  → 逐一校验原始能力是否全部满足

current_user_can('edit_post', 99)
  → WP_User::has_cap('edit_post')
  → 检查角色中是否有 edit_posts / edit_others_posts 等基础能力
  → map_meta_cap 过滤器把 'edit_post' 映射为 ['edit_posts', 'edit_others_posts'] 等"原始能力"
  → 逐一校验原始能力是否全部满足

这就是为什么代码里写 current_user_can('edit_post', 99)，实际校验的是 edit_posts、edit_others_posts 等基础能力——这种”元能力（meta capability）→ 原始能力（primitive capability）”的映射机制，是 WordPress 权限系统最精妙的部分。

2.3 六大默认角色详解

WordPress 安装后默认定义六个角色，每个角色对应不同的能力集合。下面逐一展开。

超级管理员（Super Admin）

仅存在于多站点网络（Multisite）中。拥有网络级的最高权限：可以新建/删除子站点、激活/停用网络级插件和主题、管理所有子站点的用户和内容、访问 /wp-admin/network/ 网络后台。单站点环境下不存在此角色。普通管理员在多站点下只能管理自己那个站点的设置，不能安装插件、不能升级核心——这是单站点站长切到多站点后最常踩的坑。

管理员（Administrator）

单站点下的最高权限角色。可访问所有后台菜单：文章、页面、媒体、插件、主题、用户、设置、工具。包含 manage_options、manage_categories、edit_themes、activate_plugins、delete_users、create_users、export、import 等几十个能力。给客户交付项目时，强烈建议不要把 Administrator 直接交给客户，而是创建一个权限受限的”内容管理员”角色，只保留 edit_pages、edit_posts、manage_options 等必要能力，避免客户误删主题或停用关键插件。

编辑（Editor）

可以编辑、发布、删除任何人的文章和页面，包括他人已发布的文章。包含 edit_others_posts、edit_published_posts、delete_others_posts、publish_posts、moderate_comments、manage_categories 等能力。不包含 manage_options、edit_themes、activate_plugins、用户管理能力。编辑适合作为内容团队主管，负责审核和编辑所有人提交的内容。

作者（Author）

可以写、编辑、发布、删除自己的文章。包含 edit_posts、edit_published_posts、delete_posts、delete_published_posts、publish_posts、upload_files。不能编辑他人文章，不能编辑页面（Pages），不能管理插件、主题、用户。作者适合作为博客的常驻撰稿人。

投稿者（Contributor）

可以写、编辑自己的草稿文章，但不能发布、不能上传图片。包含 edit_posts、delete_posts（仅草稿），不包含 publish_posts、upload_files、edit_published_posts。提交的文章需由编辑或管理员审核后发布。投稿者适合接受外部投稿，但需要手动给投稿者加上 upload_files 能力，否则他们写文章时无法插入配图。

订阅者（Subscriber）

只能登录、查看个人资料、修改密码。仅包含 read 能力。订阅者适合作为会员站、付费内容站的”已注册用户”基础角色。注意：开放注册时默认角色就是订阅者，但订阅者账号可被用于探测后台结构、撞库，并不像表面看那么”无害”。

2.4 六大角色关键能力对比表

下表汇总了六大默认角色对核心能力的覆盖情况（✓ = 拥有，✗ = 不拥有）：

提示：单站点下 Administrator ≈ Super Admin；切到多站点后 Administrator 会失去 install_plugins、install_themes、update_core 等能力，这些被上移到 Super Admin。

3. 深入理解 Capabilities 与 Roles

3.1 能力的完整分类

WordPress 内置能力数量庞大，按作用域可分为四大类：

文章相关能力（Post Capabilities）

• edit_posts：编辑自己的文章（包括草稿和已发布）
• edit_others_posts：编辑他人的文章
• edit_published_posts：编辑已发布状态的文章
• publish_posts：把草稿改为发布状态
• delete_posts：删除自己的文章
• delete_others_posts：删除他人的文章
• delete_published_posts：删除已发布的文章
• edit_private_posts / read_private_posts：编辑/阅读私有文章

页面相关能力（Page Capabilities）

• edit_pages：编辑自己的页面
• edit_others_pages：编辑他人页面
• edit_published_pages：编辑已发布页面
• delete_pages / delete_others_pages / delete_published_pages
• edit_theme_options：管理主题选项（菜单、小工具、背景、Logo）
• manage_themes / edit_themes / install_themes / delete_themes：主题管理

用户管理能力（User Capabilities）

• create_users：新建用户
• edit_users：编辑其他用户
• delete_users：删除用户
• list_users：在后台看到用户列表
• promote_users：调整其他用户的角色

系统管理能力（System Capabilities）

• manage_options：管理后台设置（Settings 菜单）
• manage_categories：管理文章分类和标签
• moderate_comments：审核评论
• import / export：导入导出工具
• unfiltered_html：在文章/页面中放行任意 HTML（默认仅管理员和编辑拥有）
• update_core / update_plugins / update_themes：核心和组件更新

3.2 三个 edit_posts 的关键区别

这是开发者最容易混淆的部分，必须严格区分：

最隐蔽的坑：作者（Author）发布文章后想再编辑，光有 edit_posts 是不够的，必须有 edit_published_posts。如果通过自定义角色去掉了 edit_published_posts，作者会发现自己的文章一旦发布就再也改不了——这是新手做会员系统时最常踩的雷。投稿者（Contributor）正是因为缺少 edit_published_posts 和 publish_posts，所以文章被审核发布后就无法再修改。

类似的元能力还有 edit_post_{id}（编辑某篇具体文章）、edit_private_posts、read_private_posts 等，它们都通过 map_meta_cap 由基础能力动态映射得到。

3.3 自定义文章类型的权限映射

注册自定义文章类型（CPT）时，register_post_type() 的 capability_type 参数决定该 CPT 使用哪套能力。默认是 'post'，即直接复用文章的 7 个原始能力。如果你设置 capability_type => 'book'，WordPress 会自动生成 7 个新能力：edit_books、edit_others_books、publish_books、read_private_books、delete_books、delete_private_books、delete_published_books，再通过 map_meta_cap 把 edit_book（单数元能力）映射到这 7 个原始能力。这意味着默认情况下 Administrator 自动拥有”图书”的编辑能力，但 Editor 默认没有——你需要手动给 Editor 加上 edit_books、edit_others_books 等能力，否则编辑员看不到这个 CPT 的菜单。

4. 用户角色管理实战

4.1 在后台添加新用户并分配角色

操作路径：后台 → 用户 → 添加用户。填写用户名、邮箱、名字、姓氏，在”角色”下拉框选择该用户的主角色，点击”添加用户”。WordPress 会向用户邮箱发送包含密码设置链接的邮件，用户点击链接后自行设置密码。

关键点：

• 用户名不可修改。一旦创建就终身绑定，建议用英文/拼音而不是中文，避免 URL 编码问题。
• 邮箱必须唯一，否则无法注册。
• 发送邮件功能依赖 wp_mail()，如果服务器邮件不可靠，建议装一个 SMTP 插件（如 WP Mail SMTP）确保邀请邮件能送达。
• 添加用户时勾选”跳过邮件通知”则不发送邮件，由你手动告知初始密码——但这要求你启用”任何人可注册”或开启密码重置链接。

4.2 修改用户角色（单个 / 批量）

单个修改：后台 → 用户 → 找到目标用户 → 点击”编辑” → 在”角色”下拉框中切换 → 保存。也可以在用户列表页将鼠标悬停在用户名上时出现的”快速编辑”链接里直接换角色。

批量修改：用户列表页左侧勾选多个用户 → 顶部”批量操作”下拉框选择”更改角色为…” → 选择新角色 → 点击”应用”。这是一次性给几十个用户统一换角色的最快方式。

注意：批量操作不会触发用户通知邮件，需要你自行告知受影响用户。

4.3 删除用户时的内容归属处理

删除有文章/页面的用户时，WordPress 会让你二选一：

1. 删除所有内容：该用户写的所有文章、页面、附件会被一起删除（移到回收站）。适合清理垃圾账号或离职员工且内容无价值的情况。
2. 归属转移给其他用户：把该用户的全部内容”作者”字段改成另一个用户。适合员工离职但内容需要保留并由继任者管理的场景。

生产环境删除管理员或编辑账号时，优先选择”归属转移”，避免误删大量已发布内容导致 SEO 排名下滑、内链 404。删除前先做一次数据库备份是更稳的做法。

4.4 多站点网络中的角色管理差异

多站点（Multisite）下用户管理有几个关键不同：

• 用户是网络级的：一个用户在网络中的所有子站点共享同一账号。在某个子站给用户分配的角色只对该站生效，但用户登录后可在所有有角色的子站间切换。
• 超级管理员在”网络后台 → 用户”中添加/移除用户，并可一次性勾选”添加到所有站点”或指定子站。
• 普通管理员无法添加新用户到自己的子站，必须由超级管理员操作，或开启”用户可自行注册子站”功能。
• 删除用户时多了一个选项：从网络中移除（彻底删除账号）vs 从当前站点移除（保留账号但去掉在该站的角色）。

4.5 用户注册设置（默认角色选择、开放注册的风险）

路径：后台 → 设置 → 常规 → 成员资格。

• 勾选”任何人都可以注册”后，默认新用户角色下拉框决定新注册用户的角色。绝大多数站点应选 订阅者（Subscriber）。
• 绝对不要选投稿者（Contributor）及以上作为默认角色——这等于把”写文章+发布”或”上传文件”的能力给到任何能填邮箱的注册者，垃圾内容和恶意文件上传风险陡增。
• 开放注册后建议同时：
  1. 安装一个反垃圾注册插件（如 Wordfence、Cloudflare Turnstile）拦截机器人注册；
  2. 在”设置 → 讨论”中开启评论必须经审核，避免订阅者通过评论植入垃圾链接；
  3. 给注册表单加验证码（hCaptcha 或 Cloudflare Turnstile 都是免费且隐私友好的选择）。

5. 自定义用户角色

5.1 为什么需要自定义角色

默认六个角色覆盖了博客类站点的典型场景，但实际项目里你几乎一定需要自定义角色：

• 客户站：交付项目时不能把 Administrator 给客户，但订阅者/投稿者权限又不够——需要一个”内容管理员”角色，能编辑文章/页面/媒体，但不能改主题和插件。
• 会员站：付费会员的”VIP 会员”角色，能看到隐藏内容、下载资源，但只是普通读者。
• 多部门协作：编辑部、市场部、客服部各有不同的权限边界，需要为每个部门单独定义角色。
• 第三方业务角色：WooCommerce 的”店主”、bbPress 的”版主”、LMS 插件的”讲师 / 学员”——这些插件都通过自定义角色实现业务隔离。

5.2 方法一：使用代码创建自定义角色

直接在主题的 functions.php 或独立插件中调用 add_role()：

// 在主题 functions.php 或自定义插件中
add_action( 'init', function () {
    // add_role 第二次调用时若角色已存在则返回 null，安全可重复执行
    add_role(
        'content_manager',
        __( '内容管理员', 'textdomain' ),
        [
            'read'                   => true,  // 必备，否则无法进后台
            'edit_posts'              => true,
            'edit_others_posts'       => true,
            'edit_published_posts'    => true,
            'publish_posts'           => true,
            'delete_posts'            => true,
            'delete_others_posts'     => true,
            'delete_published_posts'  => true,
            'edit_pages'              => true,
            'edit_published_pages'    => true,
            'delete_pages'            => true,
            'delete_published_pages' => true,
            'upload_files'            => true,
            'manage_categories'       => true,
            'moderate_comments'       => true,
            // 故意不给 manage_options / edit_themes / activate_plugins
        ]
    );
} );

// 在主题 functions.php 或自定义插件中
add_action( 'init', function () {
    // add_role 第二次调用时若角色已存在则返回 null，安全可重复执行
    add_role(
        'content_manager',
        __( '内容管理员', 'textdomain' ),
        [
            'read'                   => true,  // 必备，否则无法进后台
            'edit_posts'              => true,
            'edit_others_posts'       => true,
            'edit_published_posts'    => true,
            'publish_posts'           => true,
            'delete_posts'            => true,
            'delete_others_posts'     => true,
            'delete_published_posts'  => true,
            'edit_pages'              => true,
            'edit_published_pages'    => true,
            'delete_pages'            => true,
            'delete_published_pages' => true,
            'upload_files'            => true,
            'manage_categories'       => true,
            'moderate_comments'       => true,
            // 故意不给 manage_options / edit_themes / activate_plugins
        ]
    );
} );

注意：add_role() 会把角色写入 wp_user_roles 选项并永久持久化。后续注释掉这段代码角色也不会消失——需要用 remove_role('content_manager') 主动删除。建议在切换主题时通过 after_switch_theme 钩子清理自定义角色，避免遗留垃圾数据。

5.3 方法二：使用 Members 插件

Members 是 Justin Tadlock 出品的免费开源插件，是业界最主流的权限管理工具，操作步骤：

1. 后台 → 插件 → 安装 → 搜索 “Members” → 启用。
2. 启用后进入 Members → 角色管理，看到所有角色列表（含默认 6 个 + 插件角色）。
3. 点击”添加新角色”，填写角色名（英文 slug + 中文显示名）。
4. 在能力列表中勾选要赋予的能力，能力按”文章 / 页面 / 主题 / 插件 / 用户”分组展示，并可搜索。
5. 保存角色后，到”用户”页给用户分配这个新角色。
6. Members 还支持 编辑默认角色能力、为单用户分配额外能力（用户级 cap）、内容权限（针对单篇文章/页面限制访问角色）、小工具登录表单等高级功能。

5.4 方法三：使用 User Role Editor 插件

User Role Editor（URE）是另一款老牌权限插件，与 Members 的差异主要在界面：

1. 安装启用后进入 用户 → User Role Editor。
2. 顶部下拉框选择要编辑的角色（含默认角色和自定义角色）。
3. 中间区域是能力勾选区，可按分组筛选或搜索关键词。
4. 点击”添加角色”创建新角色，可基于现有角色克隆后再删减。
5. 支持”为单用户加能力”模块（付费版功能更全）。

5.5 三种自定义角色方法对比

5.6 实战案例：为”内容审核员”创建自定义角色

需求：审核员可以阅读所有文章、编辑他人文章、发布和退回草稿、审核评论，但不能删除任何内容、不能管理插件主题用户。

完整代码：

// 注册角色
add_action( 'init', function () {
    add_role(
        'content_reviewer',
        __( '内容审核员', 'textdomain' ),
        [
            'read'                   => true,
            'edit_posts'              => true,
            'edit_others_posts'       => true,
            'edit_published_posts'    => true,
            'publish_posts'           => true,  // 可发布
            'moderate_comments'       => true,
            'manage_categories'       => true,
            'upload_files'            => true,
            // 故意不赋予 delete_* 能力，避免误删内容
            'delete_posts'            => false,
            'delete_others_posts'     => false,
            'delete_published_posts'  => false,
        ]
    );
} );

// 把审核员加入后台主菜单"评论"（默认 moderate_comments 即可显示，无需额外处理）
// 限制审核员访问 tools.php 和 options-general.php
add_action( 'admin_init', function () {
    if ( current_user_can( 'content_reviewer' ) && ! current_user_can( 'manage_options' ) ) {
        remove_menu_page( 'tools.php' );
        remove_menu_page( 'options-general.php' );
    }
} );

// 注册角色
add_action( 'init', function () {
    add_role(
        'content_reviewer',
        __( '内容审核员', 'textdomain' ),
        [
            'read'                   => true,
            'edit_posts'              => true,
            'edit_others_posts'       => true,
            'edit_published_posts'    => true,
            'publish_posts'           => true,  // 可发布
            'moderate_comments'       => true,
            'manage_categories'       => true,
            'upload_files'            => true,
            // 故意不赋予 delete_* 能力，避免误删内容
            'delete_posts'            => false,
            'delete_others_posts'     => false,
            'delete_published_posts'  => false,
        ]
    );
} );

// 把审核员加入后台主菜单"评论"（默认 moderate_comments 即可显示，无需额外处理）
// 限制审核员访问 tools.php 和 options-general.php
add_action( 'admin_init', function () {
    if ( current_user_can( 'content_reviewer' ) && ! current_user_can( 'manage_options' ) ) {
        remove_menu_page( 'tools.php' );
        remove_menu_page( 'options-general.php' );
    }
} );

权限清单（仅赋予的最小集）：

6. 自定义文章类型的权限设计

6.1 register_post_type 中的 capability_type

注册 CPT 时通过 capability_type 指定使用的能力基类。默认是 'post'，意味着这个 CPT 复用文章的所有能力——任何能 edit_posts 的角色都能编辑这个 CPT，权限隔离失效。

// 默认：复用文章能力，没有隔离
register_post_type( 'book', [
    'public' => true,
    'labels' => [ 'name' => '图书' ],
    // 'capability_type' 默认 'post'
] );

// 默认：复用文章能力，没有隔离
register_post_type( 'book', [
    'public' => true,
    'labels' => [ 'name' => '图书' ],
    // 'capability_type' 默认 'post'
] );

6.2 自定义 capability_type 完整示例

要让”图书”使用独立的 7 个能力，并映射给特定角色：

// 1. 注册 CPT，使用独立的 capability_type
add_action( 'init', function () {
    register_post_type( 'book', [
        'public'            => true,
        'capability_type'   => 'book',   // 单数
        'map_meta_cap'      => true,
        'labels'            => [ 'name' => '图书' ],
        'menu_icon'         => 'dashicons-book',
    ] );
} );

// 2. 在插件激活时把能力赋予 Editor 和 Administrator
register_activation_hook( __FILE__, function () {
    $editor = get_role( 'editor' );
    foreach ( [ 'edit_books', 'edit_others_books', 'publish_books',
                'delete_books', 'delete_others_books', 'delete_published_books',
                'read_private_books', 'edit_published_books',
                'delete_private_books', 'edit_private_books' ] as $cap ) {
        $editor->add_cap( $cap );
    }
    $admin = get_role( 'administrator' );
    foreach ( [ 'edit_books', 'edit_others_books', 'publish_books',
                'delete_books', 'delete_others_books', 'delete_published_books',
                'read_private_books', 'edit_published_books',
                'delete_private_books', 'edit_private_books',
                // 管理员额外需要的"管理图书"菜单
                'manage_books' ] as $cap ) {
        $admin->add_cap( $cap );
    }
} );

// 1. 注册 CPT，使用独立的 capability_type
add_action( 'init', function () {
    register_post_type( 'book', [
        'public'            => true,
        'capability_type'   => 'book',   // 单数
        'map_meta_cap'      => true,
        'labels'            => [ 'name' => '图书' ],
        'menu_icon'         => 'dashicons-book',
    ] );
} );

// 2. 在插件激活时把能力赋予 Editor 和 Administrator
register_activation_hook( __FILE__, function () {
    $editor = get_role( 'editor' );
    foreach ( [ 'edit_books', 'edit_others_books', 'publish_books',
                'delete_books', 'delete_others_books', 'delete_published_books',
                'read_private_books', 'edit_published_books',
                'delete_private_books', 'edit_private_books' ] as $cap ) {
        $editor->add_cap( $cap );
    }
    $admin = get_role( 'administrator' );
    foreach ( [ 'edit_books', 'edit_others_books', 'publish_books',
                'delete_books', 'delete_others_books', 'delete_published_books',
                'read_private_books', 'edit_published_books',
                'delete_private_books', 'edit_private_books',
                // 管理员额外需要的"管理图书"菜单
                'manage_books' ] as $cap ) {
        $admin->add_cap( $cap );
    }
} );

6.3 map_meta_cap 的作用与使用场景

map_meta_cap 是 WordPress 权限系统的”动态能力映射”机制。当你调用 current_user_can('edit_book', 99)，WordPress 通过 map_meta_cap 过滤器把单数元能力 edit_book 转换为一组原始能力（如 edit_books + 视所有权情况追加 edit_others_books），再逐一校验。

自定义 map_meta_cap 的典型场景：

• 基于内容所有者做权限决策（如”只有文章作者能编辑自己未发布的文章”）。
• 基于状态做权限决策（如”已发布且超过 7 天的文章只能由管理员编辑”）。
• 基于业务字段做权限决策（如”只能编辑自己部门的文章”）。

示例：让”图书”在发布 7 天后只能由管理员编辑：

add_filter( 'map_meta_cap', function ( $caps, $cap, $user_id, $args ) {
    if ( $cap === 'edit_book' && isset( $args[0] ) ) {
        $post = get_post( $args[0] );
        if ( $post && $post->post_type === 'book'
             && $post->post_status === 'publish'
             && ( time() - strtotime( $post->post_date ) ) > 7 * DAY_IN_SECONDS ) {
            // 超过 7 天的已发布图书，需要 manage_options
            $caps[] = 'manage_options';
        }
    }
    return $caps;
}, 10, 4 );

add_filter( 'map_meta_cap', function ( $caps, $cap, $user_id, $args ) {
    if ( $cap === 'edit_book' && isset( $args[0] ) ) {
        $post = get_post( $args[0] );
        if ( $post && $post->post_type === 'book'
             && $post->post_status === 'publish'
             && ( time() - strtotime( $post->post_date ) ) > 7 * DAY_IN_SECONDS ) {
            // 超过 7 天的已发布图书，需要 manage_options
            $caps[] = 'manage_options';
        }
    }
    return $caps;
}, 10, 4 );

7. 权限控制进阶

7.1 current_user_can() 详解

current_user_can( string $capability, mixed $args = null ): bool 是 WordPress 中最常用的权限校验函数。它检查当前登录用户是否拥有某能力。如果传第二个参数（如文章 ID），WordPress 会先通过 map_meta_cap 把元能力转换为原始能力再校验。

// 基础用法
if ( current_user_can( 'edit_posts' ) ) {
    echo '你可以编辑文章';
}

// 元能力用法（带 ID）
if ( current_user_can( 'edit_post', $post_id ) ) {
    // 实际校验的是 edit_posts + 视所有权追加 edit_others_posts
    edit_post_link( '编辑' );
}

// 基础用法
if ( current_user_can( 'edit_posts' ) ) {
    echo '你可以编辑文章';
}

// 元能力用法（带 ID）
if ( current_user_can( 'edit_post', $post_id ) ) {
    // 实际校验的是 edit_posts + 视所有权追加 edit_others_posts
    edit_post_link( '编辑' );
}

7.2 user_can() vs current_user_can()

注意：current_user_can() 内部依赖全局 $current_user，在 REST API 或 AJAX 早期钩子中可能还未初始化——这些场景必须先调用 wp_get_current_user() 确保用户对象已加载，或使用 REST API 的 permission_callback。

7.3 模板中权限检查代码示例

// 在主题模板中按权限显示编辑按钮
if ( current_user_can( 'edit_post', get_the_ID() ) ) {
    edit_post_link( '<span class="edit-link">编辑本文</span>' );
}

// 仅对管理员显示后台管理快捷入口
if ( current_user_can( 'manage_options' ) ) {
    echo '<a href="' . admin_url() . '">进入后台</a>';
}

// 前台表单：仅作者本人能提交文章修订
$post_id = get_queried_object_id();
if ( is_user_logged_in()
     && get_current_user_id() === (int) get_post_field( 'post_author', $post_id )
     && current_user_can( 'edit_post', $post_id ) ) {
    get_template_part( 'template-parts/revision-form' );
}

// 在主题模板中按权限显示编辑按钮
if ( current_user_can( 'edit_post', get_the_ID() ) ) {
    edit_post_link( '<span class="edit-link">编辑本文</span>' );
}

// 仅对管理员显示后台管理快捷入口
if ( current_user_can( 'manage_options' ) ) {
    echo '<a href="' . admin_url() . '">进入后台</a>';
}

// 前台表单：仅作者本人能提交文章修订
$post_id = get_queried_object_id();
if ( is_user_logged_in()
     && get_current_user_id() === (int) get_post_field( 'post_author', $post_id )
     && current_user_can( 'edit_post', $post_id ) ) {
    get_template_part( 'template-parts/revision-form' );
}

7.4 AJAX 请求中的权限验证

add_action( 'wp_ajax_save_post_draft', 'my_save_post_draft' );
add_action( 'wp_ajax_nopriv_save_post_draft', '__return_false' ); // 未登录拒绝

function my_save_post_draft() {
    // 1. 校验 nonce（防 CSRF）
    check_ajax_referer( 'save_post_draft_nonce', 'nonce' );

    // 2. 校验能力（防越权）
    $post_id = intval( $_POST['post_id'] ?? 0 );
    if ( ! current_user_can( 'edit_post', $post_id ) ) {
        wp_send_json_error( [ 'message' => '无权操作' ], 403 );
    }

    // 3. 业务逻辑
    wp_update_post( [ 'ID' => $post_id, 'post_status' => 'draft' ] );
    wp_send_json_success( [ 'message' => '已保存为草稿' ] );
}

add_action( 'wp_ajax_save_post_draft', 'my_save_post_draft' );
add_action( 'wp_ajax_nopriv_save_post_draft', '__return_false' ); // 未登录拒绝

function my_save_post_draft() {
    // 1. 校验 nonce（防 CSRF）
    check_ajax_referer( 'save_post_draft_nonce', 'nonce' );

    // 2. 校验能力（防越权）
    $post_id = intval( $_POST['post_id'] ?? 0 );
    if ( ! current_user_can( 'edit_post', $post_id ) ) {
        wp_send_json_error( [ 'message' => '无权操作' ], 403 );
    }

    // 3. 业务逻辑
    wp_update_post( [ 'ID' => $post_id, 'post_status' => 'draft' ] );
    wp_send_json_success( [ 'message' => '已保存为草稿' ] );
}

7.5 REST API 中的权限控制

register_rest_route( 'myplugin/v1', '/books/(?P<id>\d+)', [
    'methods'             => 'POST',
    'callback'            => 'my_update_book',
    'permission_callback' => function ( WP_REST_Request $request ) {
        $post_id = (int) $request['id'];
        // 必须显式返回布尔值，绝不能省略
        return current_user_can( 'edit_book', $post_id );
    },
    'args'                => [
        'title' => [ 'required' => true, 'type' => 'string' ],
    ],
] );

register_rest_route( 'myplugin/v1', '/books/(?P<id>\d+)', [
    'methods'             => 'POST',
    'callback'            => 'my_update_book',
    'permission_callback' => function ( WP_REST_Request $request ) {
        $post_id = (int) $request['id'];
        // 必须显式返回布尔值，绝不能省略
        return current_user_can( 'edit_book', $post_id );
    },
    'args'                => [
        'title' => [ 'required' => true, 'type' => 'string' ],
    ],
] );

警告：WordPress 5.5+ 强制要求每个 REST 路由必须有 permission_callback，写 __return_true 是最常见的安全漏洞来源——所有未登录用户都能调用此接口。

7.6 常见权限检查错误与安全漏洞

8. 权限与安全

8.1 最小权限原则（Principle of Least Privilege）

最小权限原则是安全领域的铁律：任何角色只赋予完成其职责所需的最少能力，多余的一律不给。

落地到 WordPress：

• 给客户的角色永远不包含 edit_themes、activate_plugins、manage_options，建议另开一个”超级管理员”账号收归你（开发者）自己。
• 编辑团队不要给 manage_options，避免误改 SEO、缓存等插件配置。
• 投稿者不要给 upload_files，除非你接受任意投稿者上传文件（这是恶意文件上传的入口）。如必须给，要装防护插件扫描上传的媒体。
• 自定义角色宁可权限不足再加，也不要一次配满——补权限容易，撤权限风险高。

8.2 管理员账号安全最佳实践

• 不要用 admin 作为用户名——这是 WPScan 默认字典的第一个尝试项。装站后用 SQL 或新建管理员账号删除默认 admin。
• 管理员密码至少 16 位，含大小写数字符号。WordPress 自带密码强度指示器，但不强制——你需要配合 2FA 插件（参考 WordPress 2FA 教程）弥补密码弱的风险。
• 管理员账号数量最小化：原则上整站只有 1-2 个真正需要管理员权限的账号，其他都用自定义角色代替。
• 限制 wp-admin 访问 IP：通过 Cloudflare WAF 规则或服务器层 .htaccess 限制 /wp-admin/ 和 /wp-login.php 仅你的 IP 段可访问。
• 登录失败锁定：装 Limit Login Attempts Reloaded 或 Wordfence，针对暴力破解自动封禁 IP。

8.3 默认订阅者角色的潜在风险

订阅者表面看只有 read 能力，但实际：

• 可探测后台结构：登录后访问 /wp-admin/，能根据菜单判断你装了哪些插件、用什么主题，为后续攻击提供情报。
• 可被撞库：订阅者账号通常是开放注册得到的，密码强度低，是攻击者撞库的优先目标。
• 可发布评论：评论系统对登录用户默认免审核，订阅者可借此植入垃圾外链。
• 可访问 REST API 用户列表：/wp-json/wp/v2/users 默认对所有登录用户开放，可枚举用户名。

缓解措施：关闭开放注册；为 wp-json/wp/v2/users 加权限回调；评论一律审核；登录页加 2FA。

8.4 防止权限提升攻击

权限提升（Privilege Escalation）指低权限用户通过漏洞拿到高权限。WordPress 中的常见攻击面：

• 插件未校验权限的 AJAX 接口：攻击者构造请求，借管理员 cookie 提权。修复：所有 AJAX 必加 nonce + capability 校验。
• REST 接口 permission_callback 为 __return_true：未登录即可调用接口改数据。修复：显式返回 current_user_can(...) 结果。
• 任意文件上传：插件未限制上传文件类型，可上传 PHP webshell。修复：始终用 wp_handle_upload() 走 wp_check_filetype 校验。
• SQL 注入拼接 user_id：攻击者改 ?user_id=1 让接口改管理员资料。修复：用 current_user_can('edit_user', $user_id) 校验。

8.5 定期审计用户权限

建议每月做一次权限审计：

1. 后台 → 用户 → 列出所有用户，逐个核对角色是否合理。
2. 关注最近 30 天有无新创建的 Administrator 账号（可能是攻击者留下的后门账号）。
3. 用 WP-CLI 一键列出所有管理员：wp user list --role=administrator --fields=ID,user_login,user_email,registered_date。
4. 用 Members 插件的”角色对照”页检查每个角色当前的 cap 集合是否异常增长。
5. 多站点下还要审计 Super Admin 列表，网络后台 → 用户 → 过滤”超级管理员”。
6. 审计完保留一份 PDF/CSV 备份，留作下月对比基线。

9. 多站点网络（Multisite）权限体系

9.1 超级管理员 vs 站点管理员的权限差异

9.2 网络级设置 vs 站点级设置

多站点下配置分两层：

• 网络后台（/wp-admin/network/）：管理子站点列表、网络启用的插件和主题、网络级用户、网络注册设置、网络更新（核心升级）。这些设置对所有子站生效。
• 站点后台（/wp-admin/）：管理本站内容、本站启用的插件（必须是网络已启用的子集）、本站主题、本站用户角色（角色定义实际是网络级共享的，但本站可调整用户在本站的角色）。

9.3 多站点中的用户角色特殊性

• 用户记录存在 wp_users 主用户表，所有子站共享。但用户的角色在 wp_<site_id>_usermeta 中以 wp_<site_id>_capabilities 元字段形式存储。
• 同一个用户在 A 站是 Editor，在 B 站可以是 Subscriber——这是多站点的核心优势。
• 给用户添加子站角色：add_user_to_blog( $blog_id, $user_id, $role )。
• 移除：remove_user_from_blog( $user_id, $blog_id )。

9.4 常见配置陷阱

1. 管理员装不了插件：站长切到多站点后发现 Administrator 不能装插件——这是设计如此，需要 Super Admin 在网络后台启用。
2. 网络启用 vs 站点启用：网络启用后所有子站自动有此插件；站点启用则只有该子站有。错误地”站点启用”了本应”网络启用”的缓存插件会导致部分子站没缓存。
3. 超级管理员泄露：超级管理员账号一旦被攻破，整个网络所有子站沦陷。务必给所有 Super Admin 启用 2FA。
4. 新用户角色未分配：用户注册了网络但没在任何子站，导致登录后无任何站点可进。解决：在”网络设置 → 注册设置”中勾选”新注册用户添加到主站点”。

10. 第三方插件对权限的影响

10.1 WooCommerce 角色

WooCommerce 默认新增两个角色：

• Customer（顾客）：拥有 read，能在前台下单、查看自己订单。无法进后台（前台结账即可）。
• Shop Manager（店主）：拥有 edit_products、manage_woocommerce、view_woocommerce_reports、edit_posts 等能力，可管理订单、商品、报表。不包含 manage_options——这意味着店主不能改主题/插件，但能管 WooCommerce 设置。需要店主改非 WooCommerce 设置时要手动给 manage_options。

10.2 bbPress 角色

bbPress 论坛插件定义四个角色：

• Participant（参与者）：注册用户，可发主题和回帖，但不能管理他人内容。
• Spectator（旁观者）：只能浏览，不能发帖。适合封禁但保留账号的用户。
• Moderator（版主）：可删帖、锁定主题、移动主题。拥有 moderate 能力。
• Keymaster（论坛创建者）：论坛最高权限，可管理所有论坛设置。通常由 Administrator 担任。

10.3 BuddyPress 角色扩展

BuddyPress 不新增独立角色，而是扩展用户字段（用户组、好友、活动、消息）。它通过能力 bp_moderate 赋予管理员审核社区内容的权限。需要自定义”群组管理员”时用 groups_is_user_admin( $user_id, $group_id ) 而非 capability 校验。

10.4 插件权限冲突排查方法

• 现象：某用户能/不能做某事，与预期不符。
• 排查工具：装 User Switching 插件，可一键切换为其他用户身份验证权限，无需改密码。
• 代码级排查：

// 临时调试：输出当前用户所有能力
add_action( 'admin_footer', function () {
    if ( current_user_can( 'manage_options' ) ) {
        $user = wp_get_current_user();
        echo '<pre>' . print_r( $user->allcaps, true ) . '</pre>';
    }
} );

// 临时调试：输出当前用户所有能力
add_action( 'admin_footer', function () {
    if ( current_user_can( 'manage_options' ) ) {
        $user = wp_get_current_user();
        echo '<pre>' . print_r( $user->allcaps, true ) . '</pre>';
    }
} );

• 顺序排查：禁用所有插件 → 启用一个 → 测试 → 直到找出问题插件。
• Members 插件提供”角色编辑日志”，可看到哪个插件在何时改了角色能力，是排查冲突的最佳工具。

11. 常见问题排查

Q1：用户登录后看不到后台菜单

原因：用户角色缺少 read 能力（必备），或角色被插件改坏后能力集合为空。也可能是 auth_redirect 在用户缺少 read 时直接踢回登录页。

排查：

wp cap list <role>

wp cap list <role>

确认 read => true。如果是自定义角色，检查 add_role 是否漏写了 'read' => true。修复后强制用户重新登录。

Q2：投稿者无法上传图片

原因：投稿者默认不含 upload_files。

修复：给投稿者加 upload_files：

add_action( 'init', function () {
    $contributor = get_role( 'contributor' );
    $contributor->add_cap( 'upload_files' );
} );

add_action( 'init', function () {
    $contributor = get_role( 'contributor' );
    $contributor->add_cap( 'upload_files' );
} );

注意：这会让投稿者上传任意文件到媒体库，建议配合 Sucuri 或 Wordfence 扫描上传文件。

Q3：作者无法编辑已发布文章

原因：作者角色被改掉，缺少 edit_published_posts。常见于装了 Members 或 User Role Editor 后误删。

修复：

add_action( 'init', function () {
    get_role( 'author' )->add_cap( 'edit_published_posts' );
} );

add_action( 'init', function () {
    get_role( 'author' )->add_cap( 'edit_published_posts' );
} );

或直接在 Members 插件的角色管理页勾选 edit_published_posts。

Q4：自定义角色用户无法访问自定义文章类型

原因：注册 CPT 时设置了 capability_type => 'book'，但只给 Administrator 加了 edit_books，自定义角色（如 Editor）没加。

修复：在角色创建代码里追加：

$editor = get_role( 'editor' );
foreach ( [ 'edit_books', 'edit_others_books', 'publish_books',
            'delete_books', 'delete_others_books', 'delete_published_books',
            'read_private_books', 'edit_published_books' ] as $cap ) {
    $editor->add_cap( $cap );
}

$editor = get_role( 'editor' );
foreach ( [ 'edit_books', 'edit_others_books', 'publish_books',
            'delete_books', 'delete_others_books', 'delete_published_books',
            'read_private_books', 'edit_published_books' ] as $cap ) {
    $editor->add_cap( $cap );
}

Q5：多站点中管理员无法安装插件

原因：这是多站点的预期行为——install_plugins 能力被上移到 Super Admin。

修复：用 Super Admin 账号在网络后台 → 插件中安装并”网络启用”。或者作为 Super Admin 在网络设置里勾选”允许站点管理员安装插件”（此选项默认关闭）。

Q6：WooCommerce 店长权限不足

原因：Shop Manager 默认不含 manage_options，无法改 WordPress 通用设置、SEO 插件设置、缓存插件设置。

修复：

add_action( 'init', function () {
    get_role( 'shop_manager' )->add_cap( 'manage_options' );
} );

add_action( 'init', function () {
    get_role( 'shop_manager' )->add_cap( 'manage_options' );
} );

但这违反最小权限原则。更推荐的做法：只给店主加它真正需要的特定能力（如 SEO 插件单独的 manage_seo 能力），而不是笼统的 manage_options。

12. 最佳实践清单

按重要程度优先级排序，逐条对照执行：

1. 【最高】关闭”任何人可以注册”，除非业务必须开放。开放时默认角色只能是订阅者。
2. 【最高】删除默认 admin 用户名，用其他登录名代替，避免 WPScan 直接命中。
3. 【高】所有管理员账号启用 2FA，参考 WordPress 2FA 教程。
4. 【高】给客户交付项目时不要给 Administrator，自定义一个”内容管理员”角色即可。
5. 【高】所有 AJAX 和 REST 接口必须有 nonce + capability 双重校验，杜绝 CSRF 和 IDOR。
6. 【中】自定义角色遵循最小权限原则，宁可权限不足再加。
7. 【中】每月审计一次用户列表和角色能力清单，关注新增的 Administrator 账号。
8. 【中】自定义 CPT 必须用独立 capability_type 并显式分配给角色，避免复用 post 导致权限泄漏。
9. 【低】多站点网络下 Super Admin 账号数 ≤ 2，全部启用 2FA。
10. 【低】安装 User Switching 插件，方便权限调试和验收。

13. 常见问题 FAQ

14. 总结与行动清单

按时间线整理一份可执行的行动步骤，今天就能上手：

• 今天：检查后台 → 设置 → 常规，确认”任何人可以注册”已关闭；删除默认 admin 账号；为所有管理员启用 2FA。
• 本周：用 WP-CLI 导出用户清单做一次审计；安装 Members 插件查看每个角色的实际能力，移除多余能力；为团队成员创建最小权限的自定义角色。
• 本月：检查自定义 CPT 是否用了独立 capability_type；逐个排查 AJAX 和 REST 接口的 nonce 与 permission_callback；给客户交付时移除 Administrator 权限改为自定义角色。
• 每季度：重新审计用户列表、Super Admin 列表、插件新增的角色能力；用 User Switching 抽样验证关键角色的实际权限边界；保留审计记录作为下季对比基线。

权限管理没有”配一次就好”的事，把它当成持续的安全卫生工作，你的 WordPress 站点才能在攻击者面前真正立得住。