管理面板定制

管理面板是一个基于 React 的单页应用。它封装了 Strapi 应用的所有已安装插件。它的某些方面可以 customized，插件也可以 extend。

¥The admin panel is a React-based single-page application. It encapsulates all the installed plugins of a Strapi application. Some of its aspects can be customized, and plugins can also extend it.

要在开发时通过热重载启动 Strapi 实例，请运行以下命令：

¥To start your strapi instance with hot reloading while developing, run the following command:

cd my-app # cd into the root directory of the Strapi application project
strapi develop --watch-admin

定制选项

¥Customization options

自定义管理面板有助于更好地反映你的品牌标识或修改某些默认的 Strapi 行为：

¥Customizing the admin panel is helpful to better reflect your brand identity or to modify some default Strapi behavior:

• 访问 URL、主机和端口 可以通过服务器配置进行修改。

  ¥The access URL, host and port can be modified through the server configuration.

• 配置对象 允许替换徽标和图标、定义区域设置和扩展翻译、扩展主题以及禁用一些 Strapi 默认行为，例如显示视频教程或有关新 Strapi 版本的通知。

  ¥The configuration object allows replacing the logos and favicon, defining locales and extending translations, extending the theme, and disabling some Strapi default behaviors like displaying video tutorials or notifications about new Strapi releases.

• 所见即所得编辑器 可以更换或定制。

  ¥The WYSIWYG editor can be replaced or customized.

• 应使用用户和权限插件自定义 电子邮件模板。

  ¥The email templates should be customized using the Users and Permissions plugin.

访问网址

¥Access URL

默认情况下，管理面板通过 http://localhost:1337/admin 公开。出于安全原因，可以更新此路径。

¥By default, the administration panel is exposed via http://localhost:1337/admin. For security reasons, this path can be updated.

示例：

¥Example:

要使管理面板可从 http://localhost:1337/dashboard 访问，请在 服务器配置 文件中使用：

¥To make the admin panel accessible from http://localhost:1337/dashboard, use this in the server configuration file:

JavaScript

./config/server.js

module.exports = ({ env }) => ({
  host: env("HOST", "0.0.0.0"),
  port: env.int("PORT", 1337),
});

./config/admin.js

module.exports = ({ env }) => ({
  url: "/dashboard",
});

TypeScript

./config/server.ts

export default ({ env }) => ({
  host: env("HOST", "0.0.0.0"),
  port: env.int("PORT", 1337),
});

./config/admin.ts

export default ({ env }) => ({
  url: "/dashboard",
});

🤓 高级设置

有关更多高级设置，请参阅 管理面板配置 文档。

¥For more advanced settings please see the admin panel configuration documentation.

主机和端口

¥Host and port

✏️ 注意

从 4.15.1 开始，此功能已被弃用。Strapi 服务器现在支持在开发模式下实时更新管理面板。

¥From 4.15.1 this is now deprecated. The strapi server now supports the live updating of the admin panel in development mode.

默认情况下，前端开发服务器在 localhost:8000 上运行，但这可以修改：

¥By default, the front end development server runs on localhost:8000 but this can be modified:

JavaScript

./config/server.js

module.exports = ({ env }) => ({
  host: env("HOST", "0.0.0.0"),
  port: env.int("PORT", 1337),
});

./config/admin.js

module.exports = ({ env }) => ({
  host: "my-host", // only used along with `strapi develop --watch-admin` command
  port: 3000, // only used along with `strapi develop --watch-admin` command
});

TypeScript

./config/server.ts

export default ({ env }) => ({
  host: env("HOST", "0.0.0.0"),
  port: env.int("PORT", 1337),
});

./config/admin.ts

export default ({ env }) => ({
  host: "my-host", // only used along with `strapi develop --watch-admin` command
  port: 3000, // only used along with `strapi develop --watch-admin` command
});

配置选项

¥Configuration options

☑️ Prerequisites

在配置任何管理面板自定义选项之前，请确保：

¥Before configuring any admin panel customization option, make sure to:

• 将默认的 app.example.js 文件重命名为 app.js，

  ¥rename the default app.example.js file into app.js,

• 并在 ./src/admin/ 中新建一个 extensions 文件夹。默认情况下，Strapi 项目已在 ./src/ 中包含另一个 extensions 文件夹，但它仅用于插件扩展（请参阅 插件扩展）。

  ¥and create a new extensions folder in ./src/admin/. Strapi projects already contain by default another extensions folder in ./src/ but it is for plugins extensions only (see Plugins extension).

在 ./src/admin/app.js 找到的 config 对象存储管理面板配置。

¥The config object found at ./src/admin/app.js stores the admin panel configuration.

config 对象使用的任何文件（例如自定义徽标）应放置在 ./src/admin/extensions/ 文件夹中并导入到 ./src/admin/app.js 中。

¥Any file used by the config object (e.g. a custom logo) should be placed in a ./src/admin/extensions/ folder and imported inside ./src/admin/app.js.

config 对象接受以下参数：

¥The config object accepts the following parameters:

范围	类型	描述
auth	目的	接受 logo 密钥来替换登录屏幕上的默认 Strapi logo
head	目的	接受 favicon 密钥来替换默认的 Strapi favicon
locales	字符串数组	定义可用的区域设置（参见 更新语言环境）
translations	目的	扩展翻译
menu	目的	接受 logo 键更改主导航中的 logo
theme.light 和 theme.dark	目的	覆盖主题属性 用于浅色和夜间模式
tutorials	布尔值	切换 显示视频教程
notifications	目的	接受 releases 键（布尔值）来切换 显示有关新版本的通知

Example of a custom configuration for the admin panel

JavaScript

./my-app/src/admin/app.js

import AuthLogo from "./extensions/my-logo.png";
import MenuLogo from "./extensions/logo.png";
import favicon from "./extensions/favicon.png";

export default {
  config: {
    // Replace the Strapi logo in auth (login) views
    auth: {
      logo: AuthLogo,
    },
    // Replace the favicon
    head: {
      favicon: favicon,
    },
    // Add a new locale, other than 'en'
    locales: ["fr", "de"],
    // Replace the Strapi logo in the main navigation
    menu: {
      logo: MenuLogo,
    },
    // Override or extend the theme
    theme: {
      // overwrite light theme properties
      light: {
        colors: {
          primary100: "#f6ecfc",
          primary200: "#e0c1f4",
          primary500: "#ac73e6",
          primary600: "#9736e8",
          primary700: "#8312d1",
          danger700: "#b72b1a",
        },
      },

      // overwrite dark theme properties
      dark: {
        // ...
      },
    },
    // Extend the translations
    translations: {
      fr: {
        "Auth.form.email.label": "test",
        Users: "Utilisateurs",
        City: "CITY (FRENCH)",
        // Customize the label of the Content Manager table.
        Id: "ID french",
      },
    },
    // Disable video tutorials
    tutorials: false,
    // Disable notifications about new Strapi releases
    notifications: { releases: false },
  },

  bootstrap() {},
};

TypeScript

./my-app/src/admin/app.ts

import AuthLogo from "./extensions/my-logo.png";
import MenuLogo from "./extensions/logo.png";
import favicon from "./extensions/favicon.png";

export default {
  config: {
    // Replace the Strapi logo in auth (login) views
    auth: {
      logo: AuthLogo,
    },
    // Replace the favicon
    head: {
      favicon: favicon,
    },
    // Add a new locale, other than 'en'
    locales: ["fr", "de"],
    // Replace the Strapi logo in the main navigation
    menu: {
      logo: MenuLogo,
    },
    // Override or extend the theme
    theme: {
      colors: {
        primary100: "#f6ecfc",
        primary200: "#e0c1f4",
        primary500: "#ac73e6",
        primary600: "#9736e8",
        primary700: "#8312d1",
        danger700: "#b72b1a",
      },
    },
    // Extend the translations
    translations: {
      fr: {
        "Auth.form.email.label": "test",
        Users: "Utilisateurs",
        City: "CITY (FRENCH)",
        // Customize the label of the Content Manager table.
        Id: "ID french",
      },
    },
    // Disable video tutorials
    tutorials: false,
    // Disable notifications about new Strapi releases
    notifications: { releases: false },
  },

  bootstrap() {},
};

区域设置

¥Locales

要更新管理面板中的可用区域设置列表，请使用 config.locales 数组：

¥To update the list of available locales in the admin panel, use the config.locales array:

JavaScript

./my-app/src/admin/app.js

export default {
  config: {
    locales: ["ru", "zh"],
  },
  bootstrap() {},
};

TypeScript

./my-app/src/admin/app.ts

export default {
  config: {
    locales: ["ru", "zh"],
  },
  bootstrap() {},
};

✏️ NOTES

• en 语言环境无法从构建中删除，因为它既是后备语言环境（即，如果在语言环境中找不到翻译，则将使用 en）和默认语言环境（即，当用户第一次打开管理面板时使用） 时间）。

  ¥The en locale cannot be removed from the build as it is both the fallback (i.e. if a translation is not found in a locale, the en will be used) and the default locale (i.e. used when a user opens the administration panel for the first time).

• 可用区域设置的完整列表可在 Strapi 的 Github 存储库 上访问。

  ¥The full list of available locales is accessible on Strapi's Github repo.

扩展翻译

¥Extending translations

翻译键/值对在 @strapi/admin/admin/src/translations/[language-name].json 文件中声明。这些键可以通过 config.translations 键扩展：

¥Translation key/value pairs are declared in @strapi/admin/admin/src/translations/[language-name].json files. These keys can be extended through the config.translations key:

JavaScript

./my-app/src/admin/app.js

export default {
  config: {
    locales: ["fr"],
    translations: {
      fr: {
        "Auth.form.email.label": "test",
        Users: "Utilisateurs",
        City: "CITY (FRENCH)",
        // Customize the label of the Content Manager table.
        Id: "ID french",
      },
    },
  },
  bootstrap() {},
};

TypeScript

./my-app/src/admin/app.ts

export default {
  config: {
    locales: ["fr"],
    translations: {
      fr: {
        "Auth.form.email.label": "test",
        Users: "Utilisateurs",
        City: "CITY (FRENCH)",
        // Customize the label of the Content Manager table.
        Id: "ID french",
      },
    },
  },
  bootstrap() {},
};

插件的键/值对在 ./admin/src/translations/[language-name].json 处的插件文件中独立声明。这些键/值对可以类似地在 config.translations 键中扩展，方法是在键前面加上插件名称（即 [plugin name].[key]: 'value'），如下例所示：

¥A plugin's key/value pairs are declared independently in the plugin's files at ./admin/src/translations/[language-name].json. These key/value pairs can similarly be extended in the config.translations key by prefixing the key with the plugin's name (i.e. [plugin name].[key]: 'value') as in the following example:

JavaScript

./my-app/src/admin/app.js

export default {
  config: {
    locales: ["fr"],
    translations: {
      fr: {
        "Auth.form.email.label": "test",
        // Translate a plugin's key/value pair by adding the plugin's name as a prefix
        // In this case, we translate the "plugin.name" key of plugin "content-type-builder"
        "content-type-builder.plugin.name": "Constructeur de Type-Contenu",
      },
    },
  },
  bootstrap() {},
};

TypeScript

./my-app/src/admin/app.ts

export default {
  config: {
    locales: ["fr"],
    translations: {
      fr: {
        "Auth.form.email.label": "test",
        // Translate a plugin's key/value pair by adding the plugin's name as a prefix
        // In this case, we translate the "plugin.name" key of plugin "content-type-builder"
        "content-type-builder.plugin.name": "Constructeur de Type-Contenu",
      },
    },
  },
  bootstrap() {},
};

如果需要添加更多翻译文件，请将它们放在 ./src/admin/extensions/translations 文件夹中。

¥If more translations files should be added, place them in ./src/admin/extensions/translations folder.

标志

¥Logos

Strapi 管理面板在 2 个不同位置显示徽标，由 管理面板配置 中的 2 个不同按键表示：

¥The Strapi admin panel displays a logo in 2 different locations, represented by 2 different keys in the admin panel configuration:

用户界面中的位置	要更新的配置密钥
在登录页面上	config.auth.logo
在主导航中	config.menu.logo

Logos location in the admin panel:

The logo handled by config.auth.logo logo is only shown on the login screen.

The logo handled by config.menu.logo logo is located in the main navigation at the top left corner of the admin panel.

要更新徽标，请将图片文件放入 ./src/admin/extensions 文件夹中并更新相应的密钥。通过配置文件设置的图片文件没有大小限制。

¥To update the logos, put image files in the ./src/admin/extensions folder and update the corresponding keys. There is no size limit for image files set through the configuration files.

✏️ 注意

这两个徽标也可以直接通过管理面板进行自定义（参见 用户指南）。通过管理面板上传的徽标将取代通过配置文件设置的任何徽标。

¥Both logos can also be customized directly via the admin panel (see User Guide). Logos uploaded via the admin panel supersede any logo set through the configuration files.

网站图标

¥Favicon

要更换网站图标，请使用以下过程：

¥To replace the favicon, use the following procedure:

1. （可选）如果 ./src/admin/extensions/ 文件夹尚不存在，请创建该文件夹。

   ¥(optional) Create a ./src/admin/extensions/ folder if the folder does not already exist.

2. 将你的网站图标上传到 ./src/admin/extensions/。

   ¥Upload your favicon into ./src/admin/extensions/.

3. 将 Strapi 应用根目录中现有的 favicon.png|ico 文件替换为自定义 favicon.png|ico 文件。

   ¥Replace the existing favicon.png|ico file at the Strapi application root with a custom favicon.png|ico file.

4. 使用以下内容更新 ./src/admin/app.js：

   ¥Update ./src/admin/app.js with the following:

   ./src/admin/app.js

   import favicon from "../extensions/favicon.png";
   
   export default {
     config: {
       // replace favicon with a custom icon
       head: {
         favicon: favicon,
       },
     },
   };

5. 通过在终端中运行 yarn build && yarn develop 来重建、启动并重新访问你的 Strapi 应用。

   ¥Rebuild, launch and revisit your Strapi app by running yarn build && yarn develop in the terminal.

💡 提示

可以使用相同的过程来替换登录徽标（即 AuthLogo）和菜单徽标（即 MenuLogo）（参见 徽标定制文档）。

¥This same process may be used to replace the login logo (i.e. AuthLogo) and menu logo (i.e. MenuLogo) (see logos customization documentation).

✋ 提醒

确保清除缓存的图标。它可以缓存在你的 Web 浏览器中，也可以使用你的域管理工具（例如 Cloudflare 的 CDN）进行缓存。

¥Make sure that the cached favicon is cleared. It can be cached in your web browser and also with your domain management tool like Cloudflare's CDN.

教程视频

¥Tutorial videos

要禁用包含教程视频的信息框，请将 config.tutorials 键设置为 false。

¥To disable the information box containing the tutorial videos, set the config.tutorials key to false.

发布通知

¥Releases notifications

要禁用有关新 Strapi 版本的通知，请将 config.notifications.releases 键设置为 false。

¥To disable notifications about new Strapi releases, set the config.notifications.releases key to false.

主题扩展

¥Theme extension

Strapi 应用可以以浅色或夜间模式显示（参见 用户指南中的管理员配置文件设置），并且两者都可以通过自定义主题设置进行扩展。

¥Strapi applications can be displayed either in Light or Dark mode (see administrator profile setup in the User Guide), and both can be extended through custom theme settings.

要扩展主题，请使用：

¥To extend the theme, use either:

• config.theme.light 键用于灯光模式

  ¥the config.theme.light key for the Light mode

• config.theme.dark 键用于夜间模式

  ¥the config.theme.dark key for the Dark mode

🤓 Strapi 设计系统

默认的 Strapi 主题 定义了各种与主题相关的键（阴影、颜色……），可以通过 ./admin/src/app.js 中的 config.theme.light 和 config.theme.dark 键进行更新。Strapi 设计系统 是完全可定制的，并且有专门的 StoryBook 文档。

¥The default Strapi theme defines various theme-related keys (shadows, colors…) that can be updated through the config.theme.light and config.theme.dark keys in ./admin/src/app.js. The Strapi Design System is fully customizable and has a dedicated StoryBook documentation.

✋ 提醒

以前不带 light 或 dark 键的 config.theme 语法已被弃用，并将在下一个主要版本中删除。我们鼓励你更新自定义主题以使用支持浅色和夜间模式的新语法。

¥The former syntax for config.theme without light or dark keys is deprecated and will be removed in the next major release. We encourage you to update your custom theme to use the new syntax that supports light and dark modes.

所见即所得编辑器

¥WYSIWYG editor

要更改当前的所见即所得，你可以安装 第三方插件、创建自己的插件（请参阅 在管理面板中创建一个新字段）或利用 引导生命周期 和 extensions 系统：

¥To change the current WYSIWYG, you can install a third-party plugin, create your own plugin (see creating a new field in the admin panel) or take advantage of the bootstrap lifecycle and the extensions system:

JavaScript

./src/admin/app.js

import MyNewWYSIGWYG from "./extensions/components/MyNewWYSIGWYG"; // this file contains the logic for your new WYSIWYG

export default {
  bootstrap(app) {
    app.addFields({ type: "wysiwyg", Component: MyNewWYSIGWYG });
  },
};

TypeScript

./src/admin/app.ts

import MyNewWYSIGWYG from "./extensions/components/MyNewWYSIGWYG"; // this file contains the logic for your new WYSIWYG

export default {
  bootstrap(app) {
    app.addFields({ type: "wysiwyg", Component: MyNewWYSIGWYG });
  },
};

电子邮件模板

¥Email templates

电子邮件模板应通过管理面板使用 用户和权限插件设置。

¥Email templates should be edited through the admin panel, using the Users and Permissions plugin settings.

打包器（实验性）

¥Bundlers (experimental)

你的 Strapi 应用可以使用 2 个不同的打包器：webpack 和 vite。

¥2 different bundlers can be used with your Strapi application, webpack and vite.

Webpack

在 v4 中，这是 Strapi 用于构建管理面板的事实上的打包器。

¥In v4 this is the defacto bundler that Strapi uses to build the admin panel.

☑️ Prerequisites

在自定义 webpack 之前，请确保将默认的 webpack.config.example.js 文件重命名为 webpack.config.[js|ts]。

¥Make sure to rename the default webpack.config.example.js file into webpack.config.[js|ts] before customizing webpack.

为了扩展 webpack v5 的使用，在 ./my-app/src/admin/webpack.config.[js|ts] 内部定义一个扩展其配置的函数：

¥In order to extend the usage of webpack v5, define a function that extends its configuration inside ./my-app/src/admin/webpack.config.[js|ts]:

JavaScript

./my-app/src/admin/webpack.config.js

module.exports = (config, webpack) => {
  // Note: we provide webpack above so you should not `require` it

  // Perform customizations to webpack config
  config.plugins.push(new webpack.IgnorePlugin(/\/__tests__\//));

  // Important: return the modified config
  return config;
};

TypeScript

./my-app/src/admin/webpack.config.ts

export default (config, webpack) => {
  // Note: we provide webpack above so you should not `require` it

  // Perform customizations to webpack config
  config.plugins.push(new webpack.IgnorePlugin(/\/__tests__\//));

  // Important: return the modified config
  return config;
};

Vite

✋ 提醒

这被认为是实验性的。请报告你遇到的任何问题。

¥This is considered experimental. Please report any issues you encounter.

要将 vite 用作打包器，你需要将其作为选项传递给 strapi develop 命令：

¥To use vite as a bundler you will need to pass it as an option to the strapi develop command:

strapi develop --watch-admin --bundler=vite

要扩展 vite 的使用，请定义一个在 ./my-app/src/admin/vite.config.[js|ts] 内扩展其配置的函数：

¥To extend the usage of vite, define a function that extends its configuration inside ./my-app/src/admin/vite.config.[js|ts]:

JavaScript

./my-app/src/admin/vite.config.js

const { mergeConfig } = require("vite");

module.exports = (config) => {
  // Important: always return the modified config
  return mergeConfig(config, {
    resolve: {
      alias: {
        "@": "/src",
      },
    },
  });
};

TypeScript

./my-app/src/admin/vite,config.ts

import { mergeConfig } from "vite";

export default (config) => {
  // Important: always return the modified config
  return mergeConfig(config, {
    resolve: {
      alias: {
        "@": "/src",
      },
    },
  });
};

扩大

¥Extension

有 2 个用例可以扩展管理面板：

¥There are 2 use cases to extend the admin panel:

• 插件开发者想要开发一个 Strapi 插件，每次安装在任何 Strapi 应用中时都可以扩展管理面板。这可以通过利用 管理面板 API 来完成。

  ¥A plugin developer wants to develop a Strapi plugin that extends the admin panel everytime it's installed in any Strapi application. This can be done by taking advantage of the Admin Panel API.

• Strapi 用户只需扩展 Strapi 应用的特定实例。这可以通过直接更新 ./src/admin/app.js 文件来完成，该文件可以导入位于 ./src/admin/extensions 中的任何文件。

  ¥A Strapi user only needs to extend a specific instance of a Strapi application. This can be done by directly updating the ./src/admin/app.js file, which can import any file located in ./src/admin/extensions.

部署

¥Deployment

管理是一个调用 API 的 React 前端应用。前端和后端是独立的，可以部署在不同的服务器上，这给我们带来了不同的场景：

¥The administration is a React front-end application calling an API. The front end and the back end are independent and can be deployed on different servers, which brings us to different scenarios:

• 将整个项目部署在同一服务器上。

  ¥Deploy the entire project on the same server.

• 在与 API 服务器不同的服务器（AWS S3、Azure 等）上部署管理面板。

  ¥Deploy the administration panel on a server (AWS S3, Azure, etc) different from the API server.

每种情况的构建配置都不同。

¥Build configurations differ for each case.

在部署之前，需要通过从项目的根目录运行以下命令来构建管理面板：

¥Before deployment, the admin panel needs to be built, by running the following command from the project's root directory:

yarn

yarn build

npm

npm run build

Strapi CLI

strapi build

这将替换位于 ./build 的文件夹内容。请访问 http://localhost:1337/admin 以确保已考虑定制。

¥This will replace the folder's content located at ./build. Visit http://localhost:1337/admin to make sure customizations have been taken into account.

同一服务器

¥Same server

在同一服务器上部署管理面板和 API 是默认行为。构建配置将自动设置。服务器将在定义的端口上启动，并且可以通过 http://yourdomain.com:1337/admin 访问管理面板。

¥Deploying the admin panel and the API on the same server is the default behavior. The build configuration will be automatically set. The server will start on the defined port and the administration panel will be accessible through http://yourdomain.com:1337/admin.

💡 提示

你可能想要 更改访问管理面板的路径。

¥You might want to change the path to access the administration panel.

不同的服务器

¥Different servers

要将前端和后端部署在不同的服务器上，请使用以下配置：

¥To deploy the front end and the back end on different servers, use the following configuration:

JavaScript

./config/server.js

module.exports = ({ env }) => ({
  host: env("HOST", "0.0.0.0"),
  port: env.int("PORT", 1337),
  url: "http://yourbackend.com",
});

./config/admin.js

module.exports = ({ env }) => ({
  url: "/", // Note: The administration will be accessible from the root of the domain (ex: http://yourfrontend.com/)
  serveAdminPanel: false, // http://yourbackend.com will not serve any static admin files
});

TypeScript

./config/server.ts

export default ({ env }) => ({
  host: env("HOST", "0.0.0.0"),
  port: env.int("PORT", 1337),
  url: "http://yourbackend.com",
});

./config/admin.ts

export default ({ env }) => ({
  url: "/", // Note: The administration will be accessible from the root of the domain (ex: http://yourfrontend.com/)
  serveAdminPanel: false, // http://yourbackend.com will not serve any static admin files
});

使用此配置运行 yarn build 后，将创建/覆盖 build 文件夹。使用此文件夹从具有你选择的域（例如 http://yourfrontend.com）的另一台服务器提供服务。

¥After running yarn build with this configuration, the build folder will be created/overwritten. Use this folder to serve it from another server with the domain of your choice (e.g. http://yourfrontend.com).

管理 URL 将为 http://yourfrontend.com，来自面板的每个请求都将到达 http://yourbackend.com 的后端。

¥The administration URL will then be http://yourfrontend.com and every request from the panel will hit the backend at http://yourbackend.com.

✏️ 注意

如果你添加 url 选项的路径，它不会为你的应用添加前缀。为此，请使用 Nginx 等代理服务器（请参阅 可选软件指南）。

¥If you add a path to the url option, it won't prefix your app. To do so, use a proxy server like Nginx (see optional software guides).