Skip to main content

服务器 API：配置

🌐 Server API: Configuration

Page summary:

服务器 API 提供一个带有 default 属性和 validator 函数的 config 对象。Strapi 会将默认值与用户的 config/plugins 文件进行深度合并，然后在插件加载前运行验证。使用 strapi.plugin('my-plugin').config('key') 在运行时读取配置。

一个插件可以从其服务器入口文件暴露一个config对象。该对象定义默认的配置值，并验证从应用的config/plugins.js|ts文件加载的任何用户提供的覆盖配置。

🌐 A plugin can expose a config object from its server entry file. This object defines default configuration values and validates any user-provided overrides loaded from the application's config/plugins.js|ts file.

Prerequisites

在深入了解本页的概念之前，请确保你已经：

🌐 Before diving deeper into the concepts on this page, please ensure you have:

配置形状​

🌐 Configuration shape

config 对象接受 2 个属性：

🌐 The config object accepts 2 properties: | 属性 | 类型 | 描述 || --- | --- | --- || default | 对象，或返回对象的函数 | 插件的默认配置值。通过深度合并与用户配置合并（用户值优先）。 || validator | 函数 | 接收合并后的配置对象，如果结果无效必须抛出错误。 |

配置加载​

🌐 Configuration loading

当 Strapi 加载一个插件时，它会执行以下顺序：

🌐 When Strapi loads a plugin, it applies the following sequence: | 步骤 | Strapi 执行的操作 | 备注 || --- | --- | --- || 1 | 计算默认配置 | 如果 default 是一个函数，则以 { env } 调用它。否则直接使用该对象 || 2 | 与用户配置进行深度合并 | 来自 config/plugins.js\|ts 的值优先于默认值 || 3 | 执行 validator(mergedConfig) | 如果验证失败，会抛出带有上下文的错误，并停止启动 || 4 | 存储最终配置 | 可通过插件实例的 strapi.plugin('my-plugin').config('key') 获取 |

Note

传递给 default 函数的 { env } 参数与 Strapi 配置文件中使用的相同 env 工具。它读取 process.env 值并支持类型转换：env('MY_VAR')、env.int('PORT', 3000)、env.bool('ENABLED', true) 等。

🌐 The { env } argument passed to the default function is the same env utility used across Strapi configuration files. It reads process.env values and supports type casting: env('MY_VAR'), env.int('PORT', 3000), env.bool('ENABLED', true), etc.

配置示例​

🌐 Configuration example

/src/plugins/my-plugin/server/src/config/index.js
'use strict';

module.exports = {
  default: ({ env }) => ({
    enabled: true,
    maxItems: env.int('MY_PLUGIN_MAX_ITEMS', 10),
    endpoint: env('MY_PLUGIN_ENDPOINT', 'https://api.example.com'),
  }),
  validator: (config) => {
    if (typeof config.enabled !== 'boolean') {
      throw new Error('"enabled" must be a boolean');
    }
    if (typeof config.maxItems !== 'number' || config.maxItems < 1) {
      throw new Error('"maxItems" must be a positive number');
    }
  },
};

用户可以在应用的插件配置文件中覆盖这些值：

🌐 A user can override these values in the application's plugin configuration file:

/config/plugins.js
module.exports = {
  'my-plugin': {
    enabled: true,
    config: {
      maxItems: 25,
      endpoint: 'https://api.production.example.com',
    },
  },
};

在将默认设置与用户覆盖进行深度合并后，最终配置为 { enabled: true, maxItems: 25, endpoint: 'https://api.production.example.com' }。

🌐 After deep-merging defaults with user overrides, the final config is { enabled: true, maxItems: 25, endpoint: 'https://api.production.example.com' }.

运行时访问​

🌐 Runtime access

一旦插件被加载，其配置在任何可以访问 strapi 对象的地方都可用：

🌐 Once the plugin is loaded, its configuration is available anywhere the strapi object is accessible:

// Read one key
const maxItems = strapi.plugin('my-plugin').config('maxItems');
// Read the entire plugin config object
const pluginConfig = strapi.config.get('plugin::my-plugin');

strapi.plugin().config() 和 strapi.config.get() 通常都在生命周期函数、控制器或服务中使用。

🌐 Both strapi.plugin().config() and strapi.config.get() are typically used inside lifecycle functions, controllers, or services.

Tip

使用 yarn strapi console 或 npm run strapi console 检查正在运行的 Strapi 实例的实时配置。

🌐 Use yarn strapi console or npm run strapi console to inspect the live configuration of a running Strapi instance.

最佳实践​

🌐 Best practices

  • 始终提供一个 default。 没有默认值的插件会强制每个用户提供所有配置值，这会带来阻力。让每个选项都可选，并提供合理的默认值。
  • 对环境感知的配置，请使用 default 的函数形式。 ({ env }) => ({...}) 形式让用户无需额外设置即可使用环境变量来驱动配置。普通对象形式适合真正的静态默认值。
  • 保持验证简单明了。 validator 在启动时运行，在任何请求处理之前。抛出描述性错误，以便运算符确切知道问题出在哪里。例如，'"maxItems" must be a positive number' 比 'Invalid config' 更有用。
  • 不要在插件配置中存储秘密。 插件配置可以通过 strapi.config 在服务器端访问，如果处理不当，可能会通过日志、调试工具或自定义端点意外泄露。请直接在服务中使用环境变量，或通过 default 中的 env 助手读取这些值，而不要将原始凭据嵌入配置对象中。
  • 在服务中读取配置，而不是内联读取。 在服务方法内访问 strapi.plugin('my-plugin').config('key')，而不是在模块加载时访问，确保该值始终是最终合并的值，而不是在用户覆盖应用之前获取的快照。