Strapi v4扩展users-permission插件服务端API不生效如何解决？

正确扩展操作步骤 #

1. 目录结构配置 #

在项目根目录src/extensions下创建users-permissions文件夹（注意单词为复数形式，拼写错误是高频踩坑点），目录结构必须和官方插件结构对齐：

src/
└── extensions/
    └── users-permissions/
        ├── server/
        │   ├── controllers/  # 自定义/重写的控制器
        │   └── routes/       # 自定义路由
        └── strapi-server.js  # 插件扩展入口，必须存在

2. 编写入口文件配置 #

strapi-server.js是v4插件扩展的核心，必须在该文件中注册你新增的路由、控制器，同时给路由配置权限标识，才会在角色权限分配页显示，参考可用示例：

'use strict';

module.exports = (plugin) => {
  // 注册自定义控制器
  plugin.controllers.customController = {
    myCustomMethod: async (ctx) => {
      ctx.body = { data: "自定义接口调用成功" };
    }
  };

  // 注入自定义路由
  plugin.routes['content-api'].routes.push({
    method: 'GET',
    path: '/custom-test',
    handler: 'customController.myCustomMethod',
    config: {
      auth: {
        // scope字段是权限列表显示的必要配置
        scope: ['users-permissions:custom-test:read']
      },
      prefix: 'users-permissions'
    }
  });

  // 必须返回修改后的插件实例
  return plugin;
};

3. 清除缓存重启服务 #

修改扩展配置后直接重启服务不会生效，必须执行以下操作：

• 停止当前运行的Strapi服务
• 删除项目根目录下的.cache和build文件夹
• 执行npm run build重新打包管理端
• 执行npm run develop启动开发服务
• 刷新角色权限分配页，即可在users-permissions分组下看到新增的接口权限

常见踩坑说明 #

• 禁止直接修改node_modules/@strapi/plugin-users-permissions下的源码，Strapi运行时会优先加载src/extensions下的扩展配置，修改源码的内容会被覆盖，且依赖更新后会丢失
• 自定义路由必须配置config.auth.scope字段，无该字段的路由不会出现在权限分配列表中
• 所有扩展修改完成后必须清除缓存重打包，否则管理端不会同步更新配置

内容的提问来源于stack exchange，提问作者Sanjeet Chand