企业官网建设流程全解析

Storybook 手动指定框架初始化：create storybook --type <framework>完整指南

导读：Storybook 的初始化 CLI 在大多数情况下会自动识别你所在项目的技术栈，但当自动检测失效、项目结构非标准或构建配置被深度定制时，你需要在安装命令中显式指定框架类型。本文围绕官方文档“CLI 无法检测到我的框架”场景，完整讲解npm / pnpm / yarn create storybook --type <framework>的全部命令形态、受支持的框架类型值，并结合本仓库code/lib/create-storybook的源码，剖析--type从命令行解析、合法性校验到触发对应框架生成器的完整底层链路，帮助你从容应对任何初始化场景。

一、为什么需要手动指定框架类型

在常规流程中，运行npm create storybook@latest（或 pnpm、yarn 等价命令）后，Storybook CLI 会先对当前目录做一次项目类型探测，再据此选择对应的初始化预设（generator）与依赖。这套自动检测在大多数标准脚手架项目上都工作良好。

但在官方安装文档的故障排查章节中，Storybook 专门给出了“The CLI doesn't detect my framework”（CLI 无法检测到我的框架）这一小节。原文明确指出两类典型诉求：

• 自动检测失败：CLI 无法从当前目录判断出你使用的框架；
• 自定义项目形态：你正在使用非标准或高度定制的项目设置，无法被常规检测规则覆盖。

此时官方给出的解决方案是：在初始化命令中通过--type显式传入项目类型。该能力以docs/_snippets/create-command-manual-framework.md为承载文档，被渲染进 docs/get-started/install.mdx 的故障排查部分（见该文件 第 173-199 行），使用 Solid 框架作为示例。

二、--type支持的框架类型值一览

在介绍命令写法之前，先明确--type究竟接受哪些取值。官方安装文档在该小节中给出了完整的映射表，涵盖了当前所有可安装的框架/渲染器类型：

对照源码中定义项目类型的核心枚举 code/core/src/cli/projectTypes.ts，可以看到上表中的取值与枚举ProjectType一一对应。需要补充说明的是（可从源码确认）：该枚举还额外定义了TANSTACK_REACT = 'tanstack_react'，它在文档表格中未列出，但由于命令行参数合法集合由枚举推导而来（见下文第四节），tanstack_react同样属于可用的--type值。与此同时，枚举中的UNDETECTED（undetected）、UNSUPPORTED（unsupported）与NX（nx）不作为用户可传入的合法取值——它们仅用于内部标记自动检测的结果状态。

三、三种包管理器下手动指定框架的命令

原文档以--type solid为例，为三大主流包管理器各给出了一种等价写法，原文完整如下，可直接复制使用：

# npm npm create storybook@latest --type solid

# pnpm pnpm create storybook@latest --type solid

# yarn yarn create storybook --type solid

几条实战要点值得展开说明：

• 命令本质：npm create storybook@latest等价于通过npm exec去执行 npm 仓库中的create-storybook包，pnpm、yarn 的create子命令同理。@latest标签确保拉取到当前最新的发布版本。该 CLI 的源码与测试就位于本仓库的 code/lib/create-storybook 中，其中命令行参数解析入口是 code/lib/create-storybook/src/bin/run.ts。
• 适用范围：命令在项目根目录下运行；执行后 CLI 会为指定框架安装对应依赖、写入默认配置、补充入门 stories 并设置storybook/build-storybook等脚本。
• 与自动选择的关系：如果省略--type，CLI 会尝试自动探测；只有当你确认当前目录无法被正确识别时才需要手动指定。手动指定后走的是与自动探测完全相同的下游初始化流程，因此不会“绕过”任何必要步骤。
• 替换目标框架：只需把solid替换为第二节表格中的任意值（如--type vue3、--type sveltekit、--type angular），即可把同样的命令推广到其他技术栈。

若想进一步约束安装过程使用的包管理器，可与官方安装文档中提到的--package-manager标志搭配使用，例如npm create storybook@latest --type solid --package-manager pnpm。

四、源码视角：--type从命令行到框架生成器的完整链路

--type并非一个简单的“透传参数”，它由一条清晰的调用链驱动。结合源码逐层拆解如下。

4.1 命令解析：Comander 选项定义与合法值裁剪

CLI 入口 bin/run.ts 使用 Commander 定义了--type <type>选项，其合法值并非手工维护的数组，而是直接从ProjectType枚举推导，并剔除掉三个不可安装的哨兵值：

new Option('--type <type>', 'Add Storybook for a specific project type').choices( Object.values(ProjectType).filter( (type) => ![ProjectType.UNDETECTED, ProjectType.UNSUPPORTED, ProjectType.NX].includes(type) ) )

这意味着只要传入的值不在合法集合内，Commander 在参数解析阶段就会直接报错，从源头拦截了拼写错误（例如写成solidjs或solid-js）。

4.2 业务校验：validateProvidedType的兜底判断

参数进入初始化流程后，由ProjectDetectionCommand.execute()决定走“用户指定”还是“自动检测”分支。在 ProjectDetectionCommand.ts 中可以看到核心逻辑：

• 若options.type存在，则调用projectTypeService.validateProvidedType(projectTypeProvided)进行二次校验，并记录Installing Storybook for user specified project type: <type>日志；
• 否则才进入autoDetectProjectType自动探测路径（该路径在遇到 React Native 项目时还会额外弹窗让你选择 Native / Web / Both 变体）。

validateProvidedType的实现位于 ProjectTypeService.ts：它再次过滤掉undetected、unsupported、nx三个非可安装类型，若传入值不在白名单内，则抛出Unknown project type supplied: <type>的错误并终止初始化。因此，即使绕过了 Commander 校验（例如通过编程方式调用），业务层也会把关。

4.3 对比：自动检测失败时会发生什么

理解手动指定为何被需要，还要知道自动检测的失败路径。当没有传入--type且探测无结果时（即探测值为UNDETECTED），源码在 ProjectTypeService.ts 会打印明确的引导性错误：

Storybook couldn't detect a supported framework or configuration for your project. Make sure you're inside a framework project (e.g., React, Vue, Svelte, Angular, Next.js) and that its dependencies are installed.

提示中还包含两条建议：在空目录或新建的标准应用里运行初始化；若目录里混入无关文件，则另建干净目录。自动检测本身依赖预设模板的依赖/文件匹配规则（见 getSupportedTemplates），例如命中nuxt依赖判为 Nuxt、vue主版本为 3 判为 Vue 3、存在@angular/core判为 Angular、react-scripts或其可执行文件判为 CRA 等。当你的项目使用了 fork 的构建工具或自定义脚本导致规则不匹配时，官方推荐的出路就是回到--type手动指定。

4.4 生成器分发：类型决定初始化内容

项目类型确定后，初始化流程会依据该类型查找对应的生成器（generator）。从源码目录结构可以清晰看到这种“一类型一生成器”的映射关系：code/lib/create-storybook/src/generators/下按大写类型名组织目录，例如ANGULAR、NEXTJS、REACT、SVELTEKIT、SOLID（见 code/lib/create-storybook/src/generators/SOLID/index.ts）等，各生成器负责产出对应框架的 Storybook 依赖清单、预设与模板，最终由 GeneratorRegistry.ts 统一注册与分发。因此，--type solid与“自动探测判为 Solid”会触发同一个初始化产物，二者只是项目类型来源不同。

五、--type与其它初始化选项的搭配实战

--type通常不是单独出现的，CLI 还提供了一组可并行使用的选项（均可在 bin/run.ts 的 Commander 定义中确认）。常用组合如下：

一个完整的 CI 场景示例（以 Solid + pnpm 为例）：

pnpm create storybook@latest --type solid --package-manager pnpm --yes --no-dev

它会跳过所有交互询问，用 pnpm 完成 Solid 项目 Storybook 的安装与配置，但不立即拉起开发服务器，方便接入后续的自动化脚本。

六、小结

手动指定框架是 Storybook 初始化体系中的关键兜底能力。你需要记住的核心事实包括：

• 何时用：CLI 自动检测失败，或项目使用自定义/非标准结构时，追加--type <framework>；
• 传什么值：取值与ProjectType枚举一一对应，覆盖 React、Vue 3、Angular、Svelte、SvelteKit、Solid、Next.js、Nuxt、Qwik、Ember、Web Components、RN 系列与 Server 等 18 种以上可安装类型（tanstack_react亦在枚举中可用）；
• 为什么可靠：--type在 bin/run.ts 解析阶段即通过枚举裁剪合法值，在业务层又经 validateProvidedType 二次校验，最终触发与自动探测完全一致的框架生成器，命令行为确定且可预期。

掌握这一参数，你就能在任意框架项目中获得可复现、无歧义的 Storybook 初始化体验。更完整的安装流程与其它故障排查主题，可继续阅读 docs/get-started/install.mdx。