企业官网建设流程全解析

Storybook 中 @storybook/preact-vite 框架选项配置详解：.storybook/main 实战指南

本指南围绕 Storybook 官方文档中的preact-vite-framework-options片段，讲解在.storybook/main.js/main.ts中为 Preact + Vite 框架声明framework.options的正确写法。文章不仅还原官方配置骨架，更结合当前仓库中@storybook/preact-vite的 TypeScript 类型定义、preset 实现与 Vite builder 的参数源码，说明options究竟可以配置什么、如何透传给构建器，帮助你写出类型安全、参数精准的 Storybook 配置。

一、为什么要用framework.options？

Storybook 通过main配置文件中的framework字段来决定使用哪套渲染器与构建器组合。对 Preact 项目而言，最常用的取值是@storybook/preact-vite：它的 renderer 能力来自@storybook/preact，打包与开发服务器能力来自@storybook/builder-vite（见 code/frameworks/preact-vite/package.json 的依赖声明）。

但framework不只可以写成一个字符串，还可以写成对象形式：

framework: { name: '@storybook/preact-vite', options: { // ... }, },

options就是"框架层面的可调参数"。它不负责 Preact 组件代码本身，而是用来精细控制 Storybook 这个框架实例的构建行为——从源码类型看，这一层目前唯一暴露的入口是Vite builder 的选项（详见后文），相当于在框架与底层构建器之间保留了一条受控的配置通道。

二、配置骨架：在.storybook/main中挂载 options

官方文档片段给出了两种语言下的标准写法，与项目是否使用 TypeScript 无关，结构完全一致。

JavaScript 版本（.storybook/main.js）

export default { framework: { name: '@storybook/preact-vite', options: { // ... }, }, };

TypeScript 版本（.storybook/main.ts）

import type { StorybookConfig } from '@storybook/preact-vite'; const config: StorybookConfig = { framework: { name: '@storybook/preact-vite', options: { // ... }, }, }; export default config;

两段代码的核心语义完全一致：framework.name指向框架包，framework.options存放该框架的附加配置。TS 版本额外引入了@storybook/preact-vite导出的StorybookConfig类型，让整个 config 对象（包括framework.options内的字段）获得编译期校验——options中一旦出现框架不认识的顶层字段，类型系统就会给出提示。

三、options.builder：把参数透传给 Vite 构建器

options里究竟能放什么？这是配置者最关心的问题。综合官方页面（见 docs/get-started/frameworks/preact-vite.mdx 的 "API / Options" 小节）与源码类型定义，答案非常清晰：

• 官方 API 文档声明builder字段的类型为Record<string, any>，用于"配置框架所用构建器的选项"；
• 该框架所用的构建器即 Vite builder，其可用选项详见 docs/builders/vite.mdx。

具体到本仓库的源码，code/frameworks/preact-vite/src/types.ts 给出了严格的类型边界：

export type FrameworkOptions = { builder?: BuilderOptions; };

其中BuilderOptions从@storybook/builder-vite导入。这意味着@storybook/preact-vite的framework.options在类型层面就是一个"透传层"：配置对象本身不定义业务化参数，而是把builder下的配置原样交给 Vite 构建器。

Vite builder 支持的具体选项

查阅 code/builders/builder-vite/src/types.ts 可确认当前两个核心选项及其语义：

对应的一个可落地示例（JS 版）：

export default { framework: { name: '@storybook/preact-vite', options: { builder: { // 使用独立的 Vite 配置文件 viteConfigPath: '.storybook/vite.config.ts', }, }, }, };

TS 版在StorybookConfig约束下写法一致，且viteConfigPath、configLoader的取值会被逐字校验。

四、源码视角：options 是如何"接线"到构建器的

要理解为什么options只有一个builder通道，看框架的 preset 实现即可。当前仓库中 code/frameworks/preact-vite/src/preset.ts 的代码非常简短：

export const core: StorybookConfig['core'] = { builder: import.meta.resolve('@storybook/builder-vite'), renderer: import.meta.resolve('@storybook/preact/preset'), }; export const viteFinal: StorybookConfig['viteFinal'] = async (config) => { // TODO: Add docgen plugin per issue https://github.com/storybookjs/storybook/issues/19739 return config; };

从中可以推断出三条实现事实：

1. 框架默认不额外改动 Vite 配置：viteFinal目前原样返回config，源码注释也标明"尚未接入 docgen 插件"（对应一个 GitHub issue 的 TODO）。也就是说，当前版本下@storybook/preact-vite自身没有吃掉任何专属 options 字段，真正的扩展点都收敛到了 Vite 构建器层。
2. 构建器选项最终流入 builder：types.ts中FrameworkOptions的结构把用户输入限定在builder键下，与该 preset 声明的core.builder（@storybook/builder-vite）一一对应——框架收到的options.builder会作为 Vite 构建器初始化参数使用。
3. 同一FrameworkOptions同时约束core.builder.options：types.ts中core的类型同样复用了来自 builder 的BuilderOptions，因此你在.storybook/main.ts的framework.options.builder里写的参数，与直接在core.builder上配置所依据的类型规范是一致的。

五、从 Webpack 迁移：替换 framework 名即可启用 options

framework.options是否生效，取决于framework.name指向的是哪个框架。官方片段（见 docs/_snippets/preact-vite-add-framework.md）演示了把既有配置从旧框架切换为@storybook/preact-vite的标准动作：将framework一行从旧的@storybook/preact-webpack5改为@storybook/preact-vite（JS 与 TS 写法对称）。

迁移后如需继续细化构建参数，直接把前文所述的options对象补充到新的 framework 条目下即可，例如：

import type { StorybookConfig } from '@storybook/preact-vite'; const config: StorybookConfig = { framework: { name: '@storybook/preact-vite', options: { builder: { configLoader: 'bundle', }, }, }, }; export default config;

注意configLoader生效的前提是项目 Vite 版本不低于 6.1.0；关于版本要求的权威信息可参考 code/frameworks/preact-vite/package.json 中的peerDependencies（preact >=10、vite ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0）。

六、类型安全三件套与常见误区

使用 defineMain 提升校验体验

@storybook/preact-vite除默认入口外还暴露了./node子路径，其中 code/frameworks/preact-vite/src/node/index.ts 提供了defineMain辅助函数，配合官方 snippet 中直接 import 的StorybookConfig类型，可以二选一使用：

import { defineMain } from '@storybook/preact-vite/node'; export default defineMain({ framework: { name: '@storybook/preact-vite', options: { builder: { viteConfigPath: '.storybook/vite.config.ts', }, }, }, });

常见误区自查

• 不要往options顶层塞业务参数：按当前类型定义，options只有builder一个键，其余写法即使能跑也不会被类型系统认可。
• 不要把builder与viteFinal混为一谈：options.builder是给构建器的初始化参数；如需对 Vite 配置本身做编程式修改（追加插件、改 alias 等），应使用viteFinal钩子。
• configLoader有版本下限：在 Vite < 6.1.0 时该选项会被静默忽略，配置前请核对构建环境版本。

小结

preact-vite-framework-options看似只是一个配置骨架，但其背后贯穿了 Storybook 的框架抽象设计：framework.options是框架与底层构建器之间的受控参数通道，而@storybook/preact-vite当前只透传builder选项。掌握了.storybook/main.js/.storybook/main.ts中的书写方式，再结合viteConfigPath与configLoader两个参数及类型层面的约束，你就能像查阅任何一份 Storybook 框架文档一样，精确、无冗余地为 Preact + Vite 项目完成框架级构建配置。