Storybook 全局样式注入指南通过 preview-head.html 加载字体与全局 CSS【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook在 Storybook 中组件渲染在独立的预览 iframeCanvas内默认不加载你业务项目里的全局样式。本文以 storybook-preview-head-import-global-styles.md 为核心讲解如何通过.storybook/preview-head.html将 CDN 字体、自定义 CSS 等资源注入预览 iframe 的head让每个 story 都以真实项目样式渲染。读完你将掌握preview-head.html 的文件位置与写法、与previewHead预设和preview-body.html的配合方式以及注入内容的作用域边界与调试方法。一、为什么需要 preview-head.html预览 iframe 的样式隔离Storybook 是一个用于在隔离环境中构建、文档化和测试 UI 组件的 workshop见仓库根目录 README.md。它的故事stories渲染在名为 Canvas 的“预览 iframe”中而 Storybook 应用本身的 UIManager与 iframe 是两个独立的文档详见 story-rendering.mdx。这意味着你在业务项目index.html或全局 CSS 中定义的样式、加载的字体不会自动出现在预览 iframe 里。要让组件在 Storybook 中以接近真实项目的方式渲染就需要把需要的资源显式注入到 iframe 的head。官方文档在 styling-and-css.mdx 中明确指出如果有希望在所有 stories 中生效的全局 CSS 文件可以把它引入到.storybook/preview-head.html中——这正是本文主角场景的出处。二、核心配置preview-head.html 的写法在.storybook目录下创建preview-head.html把需要注入head的标签写进去即可。官方 snippet 给出了一个同时加载 CDN 字体与本地 CSS 的完整示例!-- Loads a font from a CDN -- link relpreconnect hrefhttps://fonts.googleapis.com / link relpreconnect hrefhttps://fonts.gstatic.com crossorigin / link hrefhttps://fonts.googleapis.com/css2?familyInter:wght100..900displayswap relstylesheet / !-- Load your CSS file -- link relstylesheet hrefpath/to/your/styles.css /写法要点拆解relpreconnect预热连接对fonts.googleapis.com与fonts.gstatic.com提前建立连接后者带crossorigin能显著缩短字体样式表与字体文件的加载延迟。familyInter:wght100..900Google Fonts 的 CSS2 API 语法100..900表示加载从细到粗的整个可变字重区间供组件在不同字重下验证效果。link relstylesheet引入本地 CSSpath/to/your/styles.css需按实际情况替换详见下文“静态资源路径”一节。扩展示例预加载本地字体与自定义脚本官方 storybook-preview-head-example.md 还展示了预加载本地字体与注入自定义 head 脚本的写法!-- Pull in static files served from your Static directory or the internet Example: main.js|ts is configured with staticDirs: [../public] and your font is located in the fonts directory inside your public directory -- link relpreload href/fonts/my-font.woff2 / !-- Or you can load custom head-tag JavaScript: -- script srchttps://use.typekit.net/xxxyyy.js/script script try { Typekit.load(); } catch (e) {} /script三、静态资源路径staticDirs 与相对路径在 preview-head.html 中引用本地资源时路径解析遵循以下规则托管在 Storybook 静态目录中的文件在main.js|ts中通过staticDirs: [../public]配置静态目录后preview-head.html 里可用根路径如/fonts/my-font.woff2直接引用这与官方 snippet 注释中的示例一致。静态文件目录的完整配置说明见 images-and-assets.mdx。仓库内相对路径link relstylesheet hrefpath/to/your/styles.css /中的路径按你项目结构替换为相对路径或可访问的 URL。四、作用域边界注入的是预览 iframe不是 Storybook UI官方在 story-rendering.mdx 中用醒目提示强调Storybook 会把preview-head.html中的标签注入到组件渲染所在的预览 iframe而不是 Storybook 应用界面。理解这条边界很重要你的全局样式会作用于所有 stories 的渲染结果保证 Canvas 中的组件观感与真实项目一致Storybook 自身的工具栏、侧边栏等 Manager UI 不会受影响因此把 reset、设计 token、字体族等“业务全局样式”放进 preview-head.html 是正确做法而不要指望它去改变 Storybook 界面主题界面主题由 addon-themes 等其他机制处理。五、程序化方案main.js 中的 previewHead 预设如果不需要静态注入而是想按环境或条件程序化地修改预览head官方提供了previewHead预设类型(head: string) string定义在 main-config-preview-head.mdx 中。官方示例仅在设置了ANALYTICS_ID环境变量时注入统计脚本export default { framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], previewHead: (head) ${head} ${ process.env.ANALYTICS_ID ? script srchttps://cdn.example.com/analytics.js/script : } , };TypeScript 项目可改用main.ts并搭配import type { StorybookConfig } from storybook/your-framework;见 main-config-preview-head.md 中的完整变体。该预设多数场景由 addon 作者 在 UI 配置阶段使用如果你只是加载静态字体和样式优先选择preview-head.html即可官方文档也给出了同样的建议。从源码实现看该能力由 core-server 的 common-preset.ts 提供previewHead预设会结合configDir读取preview-head.html模板并对环境变量插值getPreviewHeadTemplate(configDir, interpolations)后注入预览页面。也就是说两种方式最终都汇入同一条渲染管线模板中的占位与程序化追加的内容都会被合并进预览 iframe 的 head。六、配套能力preview-body.html 与全局样式导入除了head官方还提供了对称的preview-body.html注入机制见 story-rendering.mdx适用于需要向body添加自定义内容根节点的场景。例如项目使用rem/em相对单位时可通过它调整基准字号style html { font-size: 15px; } /style另外若你使用 Angular 框架官方还提供了通过angular.json的styles数组添加全局样式的方案见 styling-and-css.mdx注意同时同步到build-storybooktarget确保静态构建产物也包含这些样式——这与 preview-head.html 是互补的两条路径。七、实践清单与调试建议确认文件位置preview-head.html必须位于.storybook目录下与main.js|ts、preview.ts|tsx同级。按需加载CDN 字体适合验证用字体渲染的组件生产或离线环境建议把字体文件放入 staticDirs 目录后本地引用。检查注入结果启动storybook dev后打开任意 story 的 Canvas在开发者工具中查看 iframe 内的head确认 link/script 标签已注入、网络请求无 404。区分注入目标样式只进预览 iframe若想改动 Storybook 界面请走 Manager 侧的主题/Manager 配置机制。组合使用静态注入用preview-head.html条件注入如按环境变量用previewHead预设二者可以并存。总结.storybook/preview-head.html是 Storybook 向预览 iframe 注入全局字体、CSS 与脚本的官方入口与previewHead预设、preview-body.html共同构成完整的预览 HTML 定制体系。通过本文的示例与源码印证你可以让每个 story 在接近真实项目的样式环境下渲染同时清晰把握注入的作用域边界避免样式污染 Storybook 自身界面。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考