中间件配置

页面摘要： /config/middlewares 用于对全局中间件排序、启用自定义名称或解析路径，并暴露内置的配置选项。

./config/middlewares.js 文件用于定义 Strapi 服务器应应用的所有全局中间件。

只有出现在 ./config/middlewares.js 中的中间件才会被应用。中间件的加载遵循特定的加载顺序，并对每个中间件有某些命名约定和可选配置。

Strapi 会预先填充 ./config/middlewares.js 文件，其中包含内置的内部中间件，每个都有自己的配置选项。

加载顺序

./config/middlewares.js 文件导出一个数组，其中顺序很重要，并控制中间件栈的执行顺序：

JavaScript

module.exports = [
  // 该数组预填充了以 `strapi::` 为前缀的内置内部中间件
  'strapi::logger',
  'strapi::errors',
  'strapi::security',
  'strapi::cors',

  // 不需要任何配置的自定义中间件
  'global::my-custom-node-module', 

  // 用于查找包或路径的自定义名称
  {
    name: 'my-custom-node-module',
    config: {
      foo: 'bar',
    },
  },

  // 用于查找包或路径的自定义 resolve
  {
    resolve: '../some-dir/custom-middleware',
    config: {
      foo: 'bar',
    },
  },

  // 内部中间件的自定义配置
  {
    name: 'strapi::poweredBy',
    config: {
      poweredBy: 'Some awesome company',
    },
  },

  // 其余的内部与内置中间件
  'strapi::query',
  'strapi::body',
  'strapi::session',
  'strapi::favicon',
  'strapi::public',
];

TypeScript

export default [
  // 该数组预填充了以 `strapi::` 为前缀的内置内部中间件
  'strapi::logger',
  'strapi::cors',
  'strapi::body',
  'strapi::errors',
  // ...
  'my-custom-node-module', // 不需要任何配置的自定义中间件
  {
    // 用于查找包或路径的自定义名称
    name: 'my-custom-node-module',
    config: {
      foo: 'bar',
    },
  },
  {
    // 用于查找包或路径的自定义 resolve
    resolve: '../some-dir/custom-middleware',
    config: {
      foo: 'bar',
    },
  },
];

命名约定

全局中间件可以根据其来源分为不同类型，这定义了以下命名约定：

• 通过 npm 安装的 node 模块
• 或本地中间件（即在 ./config/middlewares.js 中创建的自定义中间件并配置）。 | -

由于它们直接从配置文件中配置和解析，因此没有命名约定。 |

可选配置

中间件可以有一个可选配置，包含以下参数：

内部中间件配置参考

Strapi 的核心包含以下内部中间件，主要用于性能、安全和错误处理：

body

body 中间件基于 koa-body。它使用 node-formidable 库来处理文件。body 接受以下选项：

有关 koa-body 可用选项的完整列表，请查看 koa-body 文档。

** 示例：body 中间件的自定义配置 **

JavaScript

module.exports = [
  // ...
  {
    name: 'strapi::body',
    config: {
      jsonLimit: '3mb',
      formLimit: '10mb',
      textLimit: '256kb',
      encoding: 'gbk',
    },
  },
  // ...
]

TypeScript

export default [
  // ...
  {
    name: 'strapi::body',
    config: {
      jsonLimit: '3mb',
      formLimit: '10mb',
      textLimit: '256kb',
      encoding: 'gbk',
    },
  },
  // ...
]

compression

compression 中间件基于 koa-compress。它接受以下选项：

示例：compression 中间件的自定义配置

JavaScript

module.exports = [
  // ...
  {
    name: 'strapi::compression',
    config: {
      br: false
    },
  },
  // ...
]

TypeScript

export default [
  // ...
  {
    name: 'strapi::compression',
    config: {
      br: false
    },
  },
  // ...
]

cors

此安全中间件涉及跨源资源共享（CORS），基于 @koa/cors。它接受以下选项：

** 示例：cors 中间件的自定义配置**

JavaScript

module.exports = [
  // ...
  {
    name: 'strapi::cors',
    config: {
      origin: ['https://example.com', 'https://subdomain.example.com', 'https://someotherwebsite.org'],
      methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'],
      headers: ['Content-Type', 'Authorization', 'Origin', 'Accept'],
      keepHeaderOnError: true,
    },
  },
  // ...
]

TypeScript

export default [
  // ...
  {
    name: 'strapi::cors',
    config: {
      origin: ['https://example.com', 'https://subdomain.example.com', 'https://someotherwebsite.org'],
      methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'],
      headers: ['Content-Type', 'Authorization', 'Origin', 'Accept'],
      keepHeaderOnError: true,
    },
  },
  // ...
]

** 示例：将 cors 中间件作为参数的函数内的自定义配置**

origin 可以接受一个符合以下签名的 Function 作为参数

export default [
  // ...
  {
    name: 'strapi::cors',
    config: {
      origin: (ctx): string | string[] => {
        const origin = ctx.request.header.origin;
        if (origin === 'http://localhost:3000') {
          return origin; // 返回值将成为 Access-Control-Allow-Origin 请求头的一部分
        }
        
        return ''; // CORS 检查失败
      }
    },
  },
  // ...
]

errors

errors 中间件处理代码抛出的错误。根据错误类型，它将适当的 HTTP 状态设置到响应中。默认情况下，任何不应暴露给最终用户的错误都将导致 500 HTTP 响应。

该中间件没有任何配置选项。

favicon

favicon 中间件提供 favicon，基于 koa-favicon。它接受以下选项：

** 示例：favicon 中间件的自定义配置**

JavaScript

module.exports = [
  // ...
  {
    name: 'strapi::favicon',
    config: {
      path: './public/uploads/custom-fav-abc123.ico'
    },
  },
  // ...
]

TypeScript

export default [
  // ...
  {
    name: 'strapi::favicon',
    config: {
      path: './public/uploads/custom-fav-abc123.ico'
    },
  },
  // ...
]

ip

ip 中间件是一个基于 koa-ip 的 IP 过滤中间件。它接受以下选项：

** 示例：ip 中间件的自定义配置**

JavaScript

module.exports = [
  // ...
  {
    name: 'strapi::ip',
    config: {
      whitelist: ['192.168.0.*', '192.168.1.*', '123.123.123.123'],
      blacklist: ['1.116.*.*', '103.54.*.*'],
    },
  },
  // ...
]

TypeScript

export default [
  // ...
  {
    name: 'strapi::ip',
    config: {
      whitelist: ['192.168.0.*', '192.168.1.*', '123.123.123.123'],
      blacklist: ['1.116.*.*', '103.54.*.*'],
    },
  },
  // ...
]

logger

logger 中间件用于记录请求日志。

要为 logger 中间件定义自定义配置，请创建一个专用配置文件（./config/logger.js）。它应导出一个对象，该对象必须是完整或部分 winstonjs logger 配置。该对象将在服务器启动时与 Strapi 的默认 logger 配置合并。

** 示例：logger 中间件的自定义配置**

JavaScript

'use strict';

const {
  winston,
  formats: { prettyPrint, levelFilter },
} = require('@strapi/logger');

module.exports = {
  transports: [
    new winston.transports.Console({
      level: 'http',
      format: winston.format.combine(
        levelFilter('http'),
        prettyPrint({ timestamps: 'YYYY-MM-DD hh:mm:ss.SSS' })
      ),
    }),
  ],
};

TypeScript

'use strict';

const {
  winston,
  formats: { prettyPrint, levelFilter },
} = require('@strapi/logger');

export default {
  transports: [
    new winston.transports.Console({
      level: 'http',
      format: winston.format.combine(
        levelFilter('http'),
        prettyPrint({ timestamps: 'YYYY-MM-DD hh:mm:ss.SSS' })
      ),
    }),
  ],
};

poweredBy

poweredBy 中间件向响应头添加一个 X-Powered-By 参数。它接受以下选项：

** 示例：poweredBy 中间件的自定义配置**

JavaScript

module.exports = [
  // ...
  {
    name: 'strapi::poweredBy',
    config: {
      poweredBy: 'Some Awesome Company <example.com>'
    },
  },
  // ...
]

TypeScript

export default [
  // ...
  {
    name: 'strapi::poweredBy',
    config: {
      poweredBy: 'Some Awesome Company <example.com>'
    },
  },
  // ...
]

query

query 中间件是一个基于 qs 的查询解析器。它接受以下选项：

** 示例：query 中间件的自定义配置 **

JavaScript

module.exports = [
  // ...
  {
    name: 'strapi::query',
    config: {
      arrayLimit: 50,
      depth: 10,
    },
  },
  // ...
]

TypeScript

export default [
  // ...
  {
    name: 'strapi::query',
    config: {
      arrayLimit: 50,
      depth: 10,
    },
  },
  // ...
]

** 示例：为长 REST 查询列表提高 arrayLimit **

使用适合你最长方括号编码列表的值（例如许多 populate[n] 条目）。根据你的需求和可接受的解析开销调整该数字。

JavaScript

module.exports = [
  // ...
  {
    name: 'strapi::query',
    config: {
      arrayLimit: 200,
    },
  },
  // ...
]

TypeScript

export default [
  // ...
  {
    name: 'strapi::query',
    config: {
      arrayLimit: 200,
    },
  },
  // ...
]

response-time

response-time 中间件为响应头启用 X-Response-Time（单位为毫秒）。

该中间件没有任何配置选项。

public

public 中间件是一个静态文件服务中间件，基于 koa-static。它接受以下选项：

示例：public 中间件的自定义配置

JavaScript

module.exports = [
  // ...
  {
    name: 'strapi::public',
    config: {
      maxAge: 86400000, // 1 天（毫秒）
    },
  },
  // ...
]

TypeScript

export default [
  // ...
  {
    name: 'strapi::public',
    config: {
      maxAge: 86400000, // 1 天（毫秒）
    },
  },
  // ...
]

security

security 中间件基于 koa-helmet。它接受以下选项：

** 示例：用于使用 AWS-S3 提供方的 security 中间件自定义配置**

JavaScript

module.exports = [
  // ...
  {
    name: 'strapi::security',
    config: {
      contentSecurityPolicy: {
        useDefaults: true,
        directives: {
          'connect-src': ["'self'", 'https:'],
          'img-src': [
            "'self'",
            'data:',
            'blob:',
            'market-assets.strapi.io',
            'yourBucketName.s3.yourRegion.amazonaws.com',
          ],
          'media-src': [
            "'self'",
            'data:',
            'blob:',
            'market-assets.strapi.io',
            'yourBucketName.s3.yourRegion.amazonaws.com',
          ],
          upgradeInsecureRequests: null,
        },
      },
    },
  },
  // ...
]

TypeScript

export default [
  // ...
  {
    name: 'strapi::security',
    config: {
      contentSecurityPolicy: {
        useDefaults: true,
        directives: {
          'connect-src': ["'self'", 'https:'],
          'img-src': [
            "'self'",
            'data:',
            'blob:',
            'market-assets.strapi.io',
            'yourBucketName.s3.yourRegion.amazonaws.com',
          ],
          'media-src': [
            "'self'",
            'data:',
            'blob:',
            'market-assets.strapi.io',
            'yourBucketName.s3.yourRegion.amazonaws.com',
          ],
          upgradeInsecureRequests: null,
        },
      },
    },
  },
  // ...
]

session

session 中间件允许使用基于 cookie 的会话，基于 koa-session。它接受以下选项：

** 示例：session 中间件的自定义配置 **

JavaScript

module.exports = [
  // ...
  {
    name: 'strapi::session',
    config: {
      rolling: true,
      renew: true
    },
  },
  // ...
]

TypeScript

export default [
  // ...
  {
    name: 'strapi::session',
    config: {
      rolling: true,
      renew: true
    },
  },
  // ...
]