Strapi CMS 改造实战：从后台换皮到 API 扩展

Strapi CMS 改造实战从后台换皮到 API 扩展【免费下载链接】documentationStrapi Documentation项目地址: https://gitcode.com/gh_mirrors/document/documentation把默认装好的 Strapi 直接交给业务方第一反应通常是这不像我们的产品。Strapi CMS 自定义就是解决这件事后台换皮、API 加端点、管住谁能动哪条数据。本文按界面 → API → 数据 → 集成四步把改造路径讲完。️ 改造清单动手前先有张地图定制点动哪里典型场景Logo / faviconsrc/admin/app.js品牌交付主题色浅色/深色src/admin/app.js的config.theme品牌 VI管理面板插件Marketplace 或自行开发插件新页面、新功能自定义 API 端点src/api/[name]/controllersroutes标准 API 覆盖不了的业务逻辑中间件src/middlewares/config/middlewares.js鉴权、日志、限流内容类型与钩子content-types/schema.jsonlifecycles.js数据结构、数据副作用字段验证schema.json的validations数据质量角色权限Users Permissions按角色隔离数据对照表格勾选你真正要改的部分没勾选的保持默认行为。后台界面把默认后台改成公司的样子换 logo 和 favicon先把图片放进src/admin/extensions再打开src/admin/app.js加两行配置登录页走config.auth.logo顶部导航走config.menu.logo。import AuthLogo from ./extensions/my-auth-logo.png; import MenuLogo from ./extensions/my-menu-logo.png; export default { config: { auth: { logo: AuthLogo }, // 登录页 logo menu: { logo: MenuLogo }, // 顶部导航 logo }, bootstrap() {}, };注意两点后面如果在面板 UI 里直接上传 logo会覆盖配置文件里写的改完 favicon 要执行yarn build yarn develop并且清浏览器缓存否则会一直看到旧图标。给后台定主题色浅色和深色分开配后台有浅色、深色两种模式配色分别在config.theme.light和config.theme.dark下。只写你要改的颜色键其余自动沿用默认主题不用照抄整套。export default { config: { theme: { light: { colors: { primary600: #4A6EFF } }, dark: { colors: { primary600: #9DB2FF } }, }, }, bootstrap() {}, };键名primary600、primary700 等遵循 Strapi Design System 的命名。改完一个主色键最好把按钮、链接、选中态都点一遍确认深色模式下对比度没问题。用插件扩展管理面板想要后台多一个页面、多一个区块先去面板里的 Marketplace 找现成插件和 provider按卡片上的安装说明装即可。注意 v4 和 v5 的插件不互通装之前先看 Strapi 版本。找不到合适的就按插件开发文档自建插件能注册导航、加页面也能挂服务端逻辑。API 层标准接口之外加自己的逻辑每个内容类型都会自动生成 CRUD API但业务总有标准接口覆盖不到的地方聚合查询、特殊入口。这两类问题都靠自定义端点解决。给 API 加一个自定义端点controller route做法是三步controller 里写逻辑、service 里放业务函数、routes 里注册路由。module.exports { async customAction(ctx) { const data await strapi.service( api::restaurant.restaurant ).customService(); ctx.body data; }, };module.exports { routes: [ { method: GET, path: /custom-action, handler: restaurant.customAction, }, ], };注意handler必须是controller.method格式路径别和自动生成的标准路由撞车冲突时启动阶段就会报错。用中间件处理鉴权和日志中间件在请求前后执行适合统一记日志、校验身份、统计耗时。应用级中间件放src/middlewares/并且必须在config/middlewares.js注册才会加载API 级中间件可以只挂到 routes 文件的config.middlewares里只影响对应路由。module.exports (config, { strapi }) { return async (ctx, next) { const start Date.now(); await next(); ctx.set(X-Response-Time, ${Date.now() - start}ms); }; };写完用yarn strapi middlewares:list确认它真的注册上了代码写了但没注册是最常见的坑。用查询参数控制返回的数据前端嫌API 返回太多时先别急着加端点。标准 API 的三个参数通常就够populate决定带哪些关联fields决定回哪些字段filters用$gte、$in、$contains等操作符过滤还支持跨关联的深层过滤。GET /api/restaurants?populate[dishes]*fields[name]*filters[stars][$gte]3多个字段条件之间默认是且的关系需要或时用$or显式包一层操作符完整列表见 filters 文档。数据层结构、校验与权限内容类型结构 生命周期钩子内容类型的结构由schema.json定义面板里的 Content-type Builder 改的就是这个文件。需要创建前补默认值、创建后发通知这类副作用时在同一目录手写lifecycles.js事件都是 before/after 成对出现的可以在event.params.data上读写数据。module.exports { async beforeCreate(event) { // 补默认值、修正输入 }, async afterCreate(event) { // 发通知、写缓存 }, };注意绕过 Strapi 直接用 knex 操作数据库钩子不会触发。给字段加验证规则数据质量靠字段定义里的validations解决写在schema.json对应字段下内置规则有min、max、isEmail、custom等。面板保存和 API 写入都会走这套校验比让每个前端各写一遍检查可靠。{ attributes: { name: { type: string, required: true }, rating: { type: integer, validations: [min:0, max:5] } } }用 Users Permissions 划分角色权限终端用户权限归 Users Permissions 管在 Roles 里建角色比如 editor然后在对应内容类型下勾选它能做的 CRUD 动作。Public 角色删不掉角色被删后其用户会自动落回 Public。另外注意区分后台管理员的权限是另一套 RBAC 体系别和终端用户角色混在一起配。集成支付、邮件、云存储怎么接思路是先在 Marketplace 里搜。云存储有现成的 upload provider邮件有 email provider不少支付、通知类能力也能找到对应插件装上按文档填配置就能用。Marketplace 没有的就在src/api/[name]/services/下自建 service把第三方 SDK 包一层再让 controller 或生命周期钩子去调用。这样集成代码集中在一处将来换供应商不用动业务代码。交付前自检按业务需求勾改造点品牌logo、favicon、主题色是否都替换API标准端点 查询参数能否满足前端特殊逻辑是否走了自定义端点中间件鉴权、日志是否注册并生效数据字段验证是否落进 schema副作用是否写进生命周期钩子权限角色划分和 Public 边界是否确认集成支付、邮件、云存储走 provider 还是自建 service关键文档仓库内路径admin-panel-customization/backend-customization/middlewares.mdbackend-customization/models.mdapi/rest/filters.mdfeatures/users-permissions.md想通读官方文档本身可以拉一份仓库git clone https://gitcode.com/gh_mirrors/document/documentation【免费下载链接】documentationStrapi Documentation项目地址: https://gitcode.com/gh_mirrors/document/documentation创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考