Fastify集成Swagger与Helmet报错：swaggerCSP未定义

使用的包版本 #

"@fastify/swagger": "^8.13.0",
"@fastify/helmet": "^11.1.1",

配置代码 #

await app.register(import('@fastify/swagger'), app.configs.swagger);
app.register(helmet, instance => {
  return {
    contentSecurityPolicy: {
      directives: {
        ...helmet.contentSecurityPolicy.getDefaultDirectives(),
        "form-action": ["'self'"],
        "img-src": ["'self'", "data:", "validator.swagger.io"],
        "script-src": ["'self'"].concat(instance.swaggerCSP.script),
        "style-src": ["'self'", "https:"].concat(
          instance.swaggerCSP.style
        ),
      }
    }
  }
})

触发的错误 #

第一个错误 #

"script-src": ["'self'"].concat(instance.swaggerCSP.script),
                                                            ^
TypeError: Cannot read properties of undefined (reading 'script')

注释script-src相关代码后出现的第二个错误 #

instance.swaggerCSP.style
                              ^
  TypeError: Cannot read properties of undefined (reading 'style')

解决方案 #

问题核心是Swagger的异步注册未完成时，Helmet就已执行配置逻辑，此时instance.swaggerCSP还未被挂载到Fastify实例上。

修正方案1：确保异步注册顺序 #

将Helmet的注册改为异步，等待Swagger注册完成后再执行：

// 先完成Swagger的异步注册
await app.register(import('@fastify/swagger'), app.configs.swagger);

// 再注册Helmet，此时实例上已存在swaggerCSP
await app.register(helmet, (instance) => {
  return {
    contentSecurityPolicy: {
      directives: {
        ...helmet.contentSecurityPolicy.getDefaultDirectives(),
        "form-action": ["'self'"],
        "img-src": ["'self'", "data:", "validator.swagger.io"],
        "script-src": ["'self'"].concat(instance.swaggerCSP.script),
        "style-src": ["'self'", "https:"].concat(instance.swaggerCSP.style),
      }
    }
  }
});

修正方案2：使用Fastify的依赖机制 #

通过dependsOn指定Helmet依赖Swagger插件，确保加载顺序正确：

// 给Swagger注册添加名称，用于依赖引用
app.register(import('@fastify/swagger'), {
  ...app.configs.swagger,
  name: 'swagger-plugin'
});

// 指定Helmet依赖Swagger插件
app.register(helmet, {
  dependsOn: 'swagger-plugin'
}, (instance) => {
  return {
    contentSecurityPolicy: {
      directives: {
        ...helmet.contentSecurityPolicy.getDefaultDirectives(),
        "form-action": ["'self'"],
        "img-src": ["'self'", "data:", "validator.swagger.io"],
        "script-src": ["'self'"].concat(instance.swaggerCSP.script),
        "style-src": ["'self'", "https:"].concat(instance.swaggerCSP.style),
      }
    }
  }
});

额外注意事项 #

如果你的Swagger配置未启用UI组件（仅生成OpenAPI文档），swaggerCSP不会被创建。此时需要确保app.configs.swagger中包含UI相关配置，例如：

const swaggerConfigs = {
  // 启用Swagger UI
  ui: true,
  // 其他Swagger配置项
  openapi: {
    // ...
  }
};

内容的提问来源于stack exchange，提问作者user10596155