服务端 API：配置（Configuration）

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

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

配置形态

config 对象接受 2 个属性：

配置加载

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

配置示例

JavaScript

'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');
    }
  },
};

TypeScript

export default {
  default: ({ env }: { env: any }) => ({
    enabled: true,
    maxItems: env.int('MY_PLUGIN_MAX_ITEMS', 10),
    endpoint: env('MY_PLUGIN_ENDPOINT', 'https://api.example.com'),
  }),
  validator: (config: { enabled: unknown; maxItems: unknown }) => {
    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');
    }
  },
};

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

JavaScript

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

TypeScript

export default {
  'my-plugin': {
    enabled: true,
    config: {
      maxItems: 25,
      endpoint: 'https://api.production.example.com',
    },
  },
};

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

运行时访问

插件加载后，只要可以访问 strapi 对象，其配置就随处可用：

// 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() 通常在生命周期函数、控制器或服务中使用。

最佳实践

• 始终提供 default。 没有默认值的插件会迫使每个用户都提供所有配置值，这会造成困扰。让每个选项都是可选的，并提供一个合理的默认值。

• 对环境感知的配置使用 default 的函数形式。 ({ env }) => ({...}) 形式让用户可以仅通过环境变量来驱动配置，而无需任何额外设置。纯对象形式适用于真正静态的默认值。

• 保持验证简单且明确。 validator 在启动时、在任何请求被处理之前运行。抛出描述性错误，以便运维人员确切知道哪里出了问题。例如，'"maxItems" must be a positive number' 比 'Invalid config' 更有用。

• 不要在插件配置中存储密钥。 插件配置可通过 strapi.config 在服务端访问，如果处理不当，可能会通过日志、调试工具或自定义端点无意中暴露。应在服务中直接使用环境变量，或在 default 中通过 env 辅助函数读取这些值，而不是将原始凭据嵌入配置对象中。

• 在 services 中读取配置，而非内联读取。 在服务方法内部（而不是在模块加载时）访问 strapi.plugin('my-plugin').config('key')，可确保该值始终是最终合并后的值，而不是在用户覆盖应用之前拍下的快照。