Storybookcore.allowedHosts配置指南在反向代理与自定义域名下安全运行 Storybook dev server【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本篇指南讲解 Storybook 主配置core.allowedHosts的完整用法它用于控制 Storybook 开发服务器对Host/Origin头的校验规则支持将本地 Storybook 实例安全地暴露给反向代理、自定义本地域名或局域网地址。读完本文你将掌握该配置项的类型与取值含义、其在 dev server 中间件中的真实执行逻辑以及如何在不同框架与 CSF Next 写法下正确落地。什么是core.allowedHosts在.storybook/main.js|ts的core字段下allowedHosts负责配置 Storybook 开发服务器dev server的允许访问主机列表用于对请求的Host与Origin头进行校验。在 Storybook 的官方配置文档 main-config-core.mdx 中其类型与默认值定义为类型string[] | true默认值[]关键行为来自 main-config-core.mdx 与源码Storybook 的 localhost 与本机局域网地址或通过--host传入的地址永远允许访问无需手动加入白名单当需要通过反向代理例如你的 Web 应用 dev server访问本地 Storybook 实例时才需要把代理使用的域名加入该列表设置为true表示关闭主机名校验官方文档明确标注此为不安全insecure做法。这一设计同时被 Storybook 自身的核心 HTTP 中间件和 Vite builder 的server.allowedHosts消费用于拦截“来历不明”的主机请求与 WebSocketHMR连接来源。配置示例如何声明允许的主机经典 CSF 3 / 传统写法在.storybook/main.js中使用 CommonJS 默认导出export default { // 将 your-framework 替换为你实际使用的框架例如 react-vite、nextjs、vue3-vite 等 framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], core: { allowedHosts: [storybook.example.local], }, };在.storybook/main.ts中则可以通过StorybookConfig类型获得完整的类型提示// 将 your-framework 替换为你实际使用的框架例如 react-vite、nextjs、vue3-vite 等 import type { StorybookConfig } from storybook/your-framework; const config: StorybookConfig { framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], core: { allowedHosts: [storybook.example.local], }, }; export default config;CSF Next实验性写法新一代的 CSF Next 实验性写法通过defineMain包裹配置对象并且不同框架需要从各自框架包的node入口导入defineMain。以react-vite或 nextjs、nextjs-vite 等 React 系框架为例// 将 your-framework 替换为你实际使用的框架例如 react-vite、nextjs、nextjs-vite import { defineMain } from storybook/your-framework/node; export default defineMain({ stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], framework: storybook/your-framework, core: { allowedHosts: [storybook.example.local], }, });纯 JavaScript 版本等价于移除全部类型注解例如// 将 your-framework 替换为你实际使用的框架例如 react-vite、nextjs、nextjs-vite import { defineMain } from storybook/your-framework/node; export default defineMain({ framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], core: { allowedHosts: [storybook.example.local], }, });vue3-viteimport { defineMain } from storybook/vue3-vite/node; export default defineMain({ framework: storybook/vue3-vite, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], core: { allowedHosts: [storybook.example.local], }, });angularimport { defineMain } from storybook/angular/node; export default defineMain({ framework: storybook/angular, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], core: { allowedHosts: [storybook.example.local], }, });web-components-viteimport { defineMain } from storybook/web-components-vite/node; export default defineMain({ framework: storybook/web-components-vite, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], core: { allowedHosts: [storybook.example.local], }, });注意以上示例中的framework占位符storybook/your-framework是文档模板写法实际项目中应替换为你安装的真实框架包名defineMain的导入路径也必须跟随框架包storybook/react-vite/node、storybook/nextjs/node、storybook/vue3-vite/node、storybook/angular/node、storybook/web-components-vite/node等。这些完整可运行示例同时也收录在代码片段源文件 docs/_snippets/main-config-core-allowed-hosts.md 中供文档站点按渲染器多标签渲染。什么时候必须配置它反向代理场景默认情况下allowedHosts: []Storybook 仅接受 localhost、本机网络地址或--host指定的地址发起的请求。当你把 Storybook 放在反向代理后面例如通过localhost:3000的 Web 应用 dev server 代理到localhost:6006的 Storybook时浏览器实际发出的Host头是代理域如storybook.example.local而不是localhost:6006。此时若不加白名单请求会被主机名校验中间件拒绝表现为页面无法打开或资源加载被拦截。--hostCLI 选项与本配置协同工作的说明可见 cli-options.mdx-h, --host [string]决定 Storybook 监听的主机设为0.0.0.0可绑定所有网卡而core.allowedHosts用于进一步限制究竟哪些主机可以访问你的实例。取值速查表取值含义安全级别[]默认仅允许 localhost 与本地/局域网地址安全默认[storybook.example.local]在默认白名单基础上额外放行列出的主机名安全且适配代理true完全关闭主机名校验任何Host/Origin都被放行不安全仅在隔离环境应急使用源码纵深校验逻辑是如何执行的类型定义allowedHosts被定义在核心配置接口CoreConfig中类型为allowedHosts?: string[] | true其 JSDoc 注明“当前主要用于 WebSocket 连接的主机名校验设为[]表示除已知本地/网络地址外全部拒绝设为true表示全部放行”见 core-common.ts。dev server 中间件注册在开发服务器启动流程storybookDevServer中主机校验中间件被第一个挂载到路由上紧随压缩中间件之后、访问控制中间件之前app.use( getHostValidationMiddleware({ host: options.host, allowedHosts: core?.allowedHosts, localAddress: options.localAddress, networkAddress: options.networkAddress, }) );对应实现见 dev-server.ts。allowedHosts从presets.apply(core)解析而来dev-server.ts因此它支持与main.ts中其他字段一致的 preset 展开机制。校验中间件的判定规则核心实现集中在 getHostValidationMiddleware.ts其判定顺序如下allowedHosts true直接放行所有主机getHostValidationMiddleware.ts若未提供Host头且非全放行模式判定非法getHostValidationMiddleware.ts容器化特例当绑定地址host 0.0.0.0且白名单为空时视为绑定所有网卡即允许所有主机——这是为 Docker 等容器环境设计的常见放行路径getHostValidationMiddleware.ts常规情况下调用host-validation-middleware的isHostAllowed(host, allowedList)进行比对其中allowedList 用户配置的allowedHosts∪ 本机 localhost 地址 ∪ 局域网network地址getHostValidationMiddleware.ts。当校验失败时中间件直接返回HTTP 403响应体为纯文本Invalid hostres.writeHead(403, { Content-Type: text/plain }); res.end(Invalid host);见 getHostValidationMiddleware.ts。默认白名单常量DEFAULT_ALLOWED_HOSTS即为[]getHostValidationMiddleware.ts。单元测试覆盖的行为矩阵仓库为该校验逻辑提供了详尽测试getHostValidationMiddleware.test.ts可从中总结出若干精确规则allowedHosts: true时malicious-site.com:6006这类任意主机都被放行中间件直接调用next()测试 L18-L31allowedHosts: []严格模式时evil.com:6006会被拒绝并返回 403Invalid host测试 L33-L49localhost、127.0.0.1、局域网 IP、自定义域名命中allowedHosts时均被放行且localhost 不要求端口精确匹配localhost:8080同样通过测试 L142-L195只要allowedHosts不是true缺失Host头的请求一律拒绝测试 L102-L116allowedHosts列表中的条目按主机名匹配、忽略端口例如allowedHosts: [my-app.example.com]可放行my-app.example.com:8443测试 L276-L2840.0.0.0仅在白名单为空时等价于“全放行”一旦显式配置了allowedHosts非空列表任意第三方主机仍会被拒绝测试 L257-L274。这些测试同时佐证了文档中“localhost 与本地/局域网地址永远允许”的表述——即使不配置任何额外主机默认行为也不会拦截本机访问。Vite builder 的协同处理allowedHosts除了驱动 Storybook 自有的 polka 中间件之外还会透传给Vite builder 自身的 dev server 配置。在 vite-server.ts 中const { allowedHosts } await presets.apply(core, {}); // ... server: { allowedHosts, middlewareMode: true, // ... }Vite 的server.allowedHosts同样用于开发期 HTTP 与 HMR WebSocket 的来源校验。这里同样存在0.0.0.0的容器特例当绑定了所有网卡且未显式声明allowedHosts或列表为空时会将其置为true以放行容器化环境中的访问vite-server.ts。这一点值得注意即便使用 Webpack builderStorybook 核心层的 dev-server.ts 主机校验中间件依然生效因为它注册在框架无关的服务器层而 Vite builder 用户还需留意 Vite 自身的allowedHosts会被本配置直接接管两端行为保持一致。最佳实践与安全建议按需最小授权仅把确需访问 Storybook 的自定义域名含反向代理域名、团队内部域名加入allowedHosts避免使用true关闭校验。官方将true明确定位为不安全选项仅适合完全隔离的本地调试网络。配合--host使用若在容器或 CI 中需要绑定所有网卡可运行storybook dev --host 0.0.0.0此时若不配置白名单校验层会自动放行容器语义若同时配置了非空allowedHosts则仍会按白名单严格校验。无需添加 localhostlocalhost、127.0.0.1与局域网地址在任何配置下都可通过校验不要把时间浪费在把这些地址加进白名单上。诊断排错若通过代理访问 Storybook 时页面报错或资源被拒先确认响应是否为 403Invalid host——若是说明请求来源未命中白名单把代理实际使用的Host主机名加入core.allowedHosts数组即可。类型安全TypeScript 用户通过import type { StorybookConfig } from storybook/your-framework可获得core.allowedHosts的完整类型提示string[] | true避免误写配置结构。小结core.allowedHosts是让 Storybook dev server 安全“走出去”的关键开关它通过Host/Origin头校验阻止未知主机访问本地实例同时为反向代理、自定义域名与容器网络等真实场景保留了受控的放行通道。理解其默认白名单localhost/局域网永远可用、[]/字符串数组/true三种取值的语义以及0.0.0.0绑定下的容器特例能帮助你在本地开发与团队协作环境中既不被 403 阻断也不至于因一刀切关闭校验而引入安全风险。相关源码与测试可继续阅读 getHostValidationMiddleware.ts、dev-server.ts、core-common.ts 与 getHostValidationMiddleware.test.ts 以深入验证上述行为。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考