管理后台面板

Payload 动态生成一个美观且完全类型安全的 Admin Panel（管理面板），用于管理你的用户和数据。即使包含 100 多个字段，它依然保持高性能，并支持超过 30 种语言。在 Admin Panel 中，你可以管理内容、渲染你的网站、预览草稿、比较版本差异等等。

Admin Panel 设计支持品牌白标化。你可以通过替换自定义组件来无限定制和扩展 Admin UI——从简单的字段标签到整个视图都可以修改或替换，为你的编辑人员完美定制界面。

Admin Panel 使用 TypeScript 编写，基于 React 和 Next.js App Router 构建。它支持 React Server Components，可以在前端使用本地 API。你可以通过一行代码将 Payload 安装到任何现有的 Next.js 应用中，并部署到任何地方。

重新设计的 Admin Panel 带有默认展开的可折叠侧边栏，提供更强的扩展性和优化的横向空间利用。

项目结构

Admin Panel 作为 Payload 的完整 HTTP 层，为你的应用提供全面的 CRUD 接口。这意味着 REST 和 GraphQL API 都只是 Next.js 路由，它们直接与你的前端应用共存。

当你安装 Payload 后，以下文件和目录将在你的应用中创建：

app/
├─ (payload)/
├── admin/
├─── [[...segments]]/
├──── page.tsx
├──── not-found.tsx
├── api/
├─── [...slug]/
├──── route.ts
├── graphql/
├──── route.ts
├── graphql-playground/
├──── route.ts
├── custom.scss
├── layout.tsx

如上所示，所有 Payload 路由都嵌套在 (payload) 路由组内。这通过限定所有布局和样式的作用范围，在 Admin Panel 和你的应用其他部分之间创建了边界。例如，该目录下的 layout.tsx 文件是 Payload 管理文档 html 标签的地方，用于设置正确的 lang 和 dir 等属性。

admin 目录包含与界面本身相关的所有 页面，而 api 和 graphql 目录则包含与 REST API 和 GraphQL API 相关的所有 路由。所有 admin 路由都可以轻松配置以满足你的应用需求。

最后，custom.scss 文件是你可以在 Admin Panel 中添加或覆盖全局样式的地方，例如修改调色板。仅通过 CSS 自定义外观是 Admin Panel 的强大功能之一，了解更多。

所有自动生成的文件顶部都会包含以下注释：

/* 此文件由 PAYLOAD 自动生成。 */,
/* 请勿修改，因为它可能在任何时候被重写。 */

管理面板选项

所有管理面板的选项都在你的 Payload 配置 中的 admin 属性下定义：

import { buildConfig } from 'payload'

const config = buildConfig({
  // ...
  admin: {
    // highlight-line
    // ...
  },
})

以下是可用的选项：

管理员用户集合

要指定允许登录管理面板的集合，请将 admin.user 键设置为任意启用认证的集合的 slug：

import { buildConfig } from 'payload'

const config = buildConfig({
  // ...
  admin: {
    user: 'admins', // highlight-line
  },
})

默认情况下，如果未指定集合，Payload 会自动提供一个可访问管理面板的 User 集合。你可以通过添加自己的 slug: 'users' 集合来自定义或覆盖默认 User 集合的字段和设置。这样做会强制 Payload 使用你提供的 User 集合而非默认版本。

只要集合支持认证，你可以使用任意集合来访问管理面板，集合名称不必是 users。例如，你可能希望有两个同时支持认证的集合：

• admins - 拥有更高级别的权限来管理数据和访问管理面板
• customers - 用于应用程序的终端用户，不应允许其登录管理面板

要实现这一点，只需在配置中指定 admin: { user: 'admins' }。这将仅允许 admins 访问管理面板。任何以 customers 身份认证的用户都将被阻止访问管理面板。完整详情请参阅访问控制。

基于角色的访问控制

你也可以通过基于角色的访问控制（RBAC）允许具有不同权限的多种用户类型进入 Admin Panel。例如，你可能希望在 admins Collection 中设置两种角色：

• super-admin - 拥有 Admin Panel 的完全访问权限，可以执行任何操作
• editor - 仅限管理内容的有限访问权限

要实现这一点，请在你的启用了身份验证的 Collection 中添加 roles 或类似字段，然后使用 access.admin 属性根据该字段的值来授予或拒绝访问权限。完整详情请参阅访问控制。要查看一个完整的、可运行的基于角色的访问控制示例，请查看官方的Auth Example。

自定义路由

你可以完全控制 Payload 绑定的路由。这包括根级路由（如REST API）和管理级路由（如用户账户页面）。只需在配置中指定所需路径，即可根据应用程序需求自定义这些路由。

根级路由

根级路由是指不位于 /admin 路径下的路由，例如 REST API 和 GraphQL API，或者是 Admin Panel 本身的根路径。

要自定义根级路由，可以在 Payload Config 中使用 routes 属性：

import { buildConfig } from 'payload'

const config = buildConfig({
  // ...
  routes: {
    admin: '/custom-admin-route', // highlight-line
  },
})

以下是可用的配置选项：

自定义根级路由

你可以根据需要修改根级路由，例如将 Admin Panel 挂载到应用的根路径。

更改根级路由还需要相应调整项目结构以匹配新路由。例如，如果将 routes.admin 设置为 /，则需要从项目结构中完全移除 admin 目录：

app/
├─ (payload)/
├── [[...segments]]/
├──── ...

管理级别路由

管理级别路由是指位于 /admin 路径下的路由。这些路由是 Admin Panel 本身的组成部分，例如用户账户页面、登录页面等。

要自定义管理级别路由，可以在 Payload Config 中使用 admin.routes 属性：

import { buildConfig } from 'payload'

const config = buildConfig({
  // ...
  admin: {
    routes: {
      account: '/my-account', // highlight-line
    },
  },
})

以下是可用的配置选项：

国际化 (I18n)

Payload 管理面板已翻译成 30 多种语言且持续增加中。系统会根据用户的浏览器自动检测语言，并使用该语言显示管理面板中的所有文本。如果未检测到语言或用户的语言尚未支持，将默认使用英语。用户可以通过账户页面轻松选择自己的语言。更多信息请参阅 国际化。

浅色与深色模式

管理面板中的用户可以选择浅色模式或深色模式来获得不同的编辑体验。用户可以从账户页面选择自己喜欢的主题。选择后，该偏好会保存到用户设置中，并在不同会话和设备间保持。如果用户未选择主题，管理面板将自动检测操作系统主题并以此作为默认设置。

时区设置

admin.timezones 配置允许你为 Admin Panel 设置时区选项。你可以自定义可用的时区列表，未来还将支持为 Admin Panel 和所有用户配置默认时区。

可用选项如下：

我们会通过将支持时区数组中的值与 Intl API 支持的 IANA 时区列表（特别是 Intl.supportedValuesOf('timeZone')）进行比对来验证其有效性。