企业官网建设流程全解析

Storybook 指定包管理器安装指南：--package-manager参数详解

Storybook 的官方 CLI 会自动检测当前项目使用的包管理器并据此初始化依赖，但在 monorepo、CI、多包管理器混用等场景下，你可能需要强制指定某一种包管理器来完成安装。本指南以 docs/_snippets/create-command-custom-package-manager.md 为主线，结合仓库源码讲解--package-manager参数的用法、可选值范围与底层实现原理，帮助你稳定复现可预期的安装行为。

一、文档背景：这段片段在官方文档中的位置

create-command-custom-package-manager.md是 Storybook 官方文档站中可复用的"代码片段"（Code Snippet），被引用在 docs/get-started/install.mdx 的 Troubleshooting 一节"Run Storybook with other package managers"中：

The Storybook CLI includes support for the industry's popular package managers (e.g., Yarn, npm, and pnpm) automatically detecting the one you are using when you initialize Storybook. However, if you want to use a specific package manager as the default, add the--package-managerflag to the installation command.

也就是说：默认行为是自动检测，需要指定时才显式传--package-manager。

该片段中的完整命令如下：

npm create storybook@latest --package-manager=npm

pnpm create storybook@latest --package-manager=npm

yarn create storybook --package-manager=npm

说明：上面三段是同一份"按访问者包管理器切换显示"的代码片段。文档为了演示以 npm 作为目标管理器，三个示例统一传了--package-manager=npm。在实际使用中，这个值应替换为你真正想用来安装依赖的包管理器（见下文"可选值范围"）。

二、理解三行命令的启动方式差异

npm create storybook、pnpm create storybook与yarn create storybook三者只是把create-storybook引导包下载并执行的方式不同，真正做初始化的是同一个 CLI（对应仓库中的 code/lib/create-storybook 包）：

• npm create storybook@latest等价于npm init storybook@latest，由 npm 临时下载并执行create-storybook；
• pnpm create storybook@latest由 pnpm 完成同样的引导，常用于 pnpm 项目；
• yarn create storybook是 Yarn 1 时代的写法（Yarn Berry 同样兼容），文档片段中未附带版本 tag，如需固定版本可参考 docs/_snippets/create-command-custom-version.md 的版本写法。

注意二者语义的区别：npm/pnpm/yarn create决定"用哪个包管理器把 create-storybook 拉下来跑"，而--package-manager决定"create-storybook 在初始化时用哪个包管理器去安装 Storybook 及其依赖、写入 package.json 脚本"。前者管引导，后者管落地，这是整个参数体系里最容易被混淆的一点。

对应地，不带该参数的默认安装命令见 docs/_snippets/create-command.md。

三、--package-manager的源码实现与可选值

3.1 CLI 参数定义

在 create-storybook 的入口 code/lib/create-storybook/src/bin/run.ts#L40-L43 中，该参数由 Commander 声明：

.addOption( new Option('--package-manager <type>', 'Force package manager for installing deps').choices( Object.values(PackageManagerName) ) )

其中两处关键信息：

1. 作用描述：Force package manager for installing deps（强制指定用于安装依赖的包管理器）；
2. 取值被限定（choices）：只能是PackageManagerName枚举中的值。

3.2 可选值的真实范围

PackageManagerName枚举定义在 code/core/src/common/js-package-manager/JsPackageManager.ts#L24-L30：

export enum PackageManagerName { NPM = 'npm', YARN1 = 'yarn1', YARN2 = 'yarn2', PNPM = 'pnpm', BUN = 'bun', }

因此源码层面--package-manager实际接受npm、yarn1、yarn2、pnpm、bun五个值，其中 Yarn 被细分为 Classic（v1）与 Berry（v2）两个实现，各自走不同的代理逻辑。官方文档表格（docs/api/cli-options.mdx#L134）中简写为 "npm、yarn、pnpm"，是为了便于阅读的概括。

值得留意的是：即使你的项目里装了 Yarn Berry（v2），手动显式传--package-manager=yarn1也是被允许但通常不建议的——两个版本的 hoisting 行为差异很大。源码中还专门处理了"空目录 + Yarn 1"的组合，见下节。

3.3 参数如何参与安装流程

--package-manager的真正消费点在预检命令 code/lib/create-storybook/src/commands/PreflightCheckCommand.ts#L41-L72：

let packageManagerType = JsPackageManagerFactory.getPackageManagerType(); // ...（空目录场景下的 yarn1 回退逻辑）... const packageManager = JsPackageManagerFactory.getPackageManager({ force: options.packageManager, });

逻辑分三步：

1. 先自动探测：JsPackageManagerFactory.getPackageManagerType()会按当前目录存在的锁文件（yarn.lock、pnpm-lock.yaml、package-lock.json、bun.lockb等）推断默认类型，Yarn 1 与 Yarn 2+ 通过解析版本区分；
2. 显式值优先：若传入了--package-manager，则以force字段覆盖自动探测结果；
3. 构造代理对象：getPackageManager({ force })返回对应的JsPackageManager子类代理（NPMProxy / Yarn1Proxy / Yarn2Proxy / PNPMProxy / BUNProxy），后续所有依赖安装、脚本注入、版本查询都经由该代理执行。

这与"是否安装依赖、写入哪些脚本"无关，只影响"用什么工具去执行这些操作"。

这段逻辑有完备的测试支撑，例如 code/core/src/common/js-package-manager/JsPackageManagerFactory.test.ts 中对npm、pnpm、yarn1、yarn2、bun分别传入force进行构造验证。

四、一个需要避开的坑：空目录中的 Yarn 1 会回退

在空目录（或仅含极少量文件）中初始化时，CLI 会先走"脚手架新建项目"分支。PreflightCheckCommand在此处有一段保护逻辑（code/lib/create-storybook/src/commands/PreflightCheckCommand.ts#L49-L57）：

在空目录中使用 yarn1 初始化，极大概率会因各种不再修复的 hoisting 问题而失败，因此会回退到 npm。

无论 yarn1 是被自动探测到的，还是你显式用--package-manager=yarn1指定的，只要目标是空目录，CLI 都会打印警告Empty directory with yarn1 is unsupported. Falling back to npm.并把类型改写为npm。

如果你在空目录/纯脚手架场景确实想用 Yarn，建议使用yarn2（Berry）；官方同时建议优先考虑 pnpm、npm 这类 hoisting 行为更可预测的管理器。

五、实际操作：三种常见使用形态

5.1 强制使用你偏好的管理器（推荐形态）

以显式指定 pnpm 为例（把pnpm替换成npm、yarn1、yarn2、bun即可）：

# npm 环境 npm create storybook@latest --package-manager=pnpm # pnpm 环境 pnpm create storybook@latest --package-manager=pnpm # Yarn 环境 yarn create storybook --package-manager=pnpm

提示：引导方式（npm/pnpm/yarn create）与目标管理器（--package-manager的值）不要求一致。例如用yarn create引导、再强制--package-manager=npm也是合法组合——这正是文档片段演示的形式。

5.2 与版本指定组合

可同时使用自定义版本（详见 docs/_snippets/create-command-custom-version.md）：

npm create storybook@8.3 --package-manager=pnpm pnpm create storybook@8.3 --package-manager=pnpm

注意pnpm create storybook@8.3这类带版本写法要求 Storybook 8.3 及以上；更早版本需改用init命令族。

5.3 与项目类型（--type）组合

当自动探测框架失败或你使用自定义结构时，可配合--type显式指定框架（docs/_snippets/create-command-manual-framework.md）：

npm create storybook@latest --type solid --package-manager=pnpm yarn create storybook --type solid --package-manager=pnpm

官方允许的--type取值见 docs/get-started/install.mdx 中的表格，覆盖angular、react、vue3、nextjs、svelte、solid、react_native等主流框架。

六、不止 create：整个 CLI 家族都支持该参数

--package-manager并不是 create-storybook 独有。在 docs/api/cli-options.mdx 中，该参数在以下命令中均有相同语义，用于保证跨命令的一致体验：

例如：

npx storybook@latest add @storybook/addon-a11y --package-manager pnpm npx storybook@latest upgrade --package-manager pnpm

统一使用同一个管理器贯穿"安装→装插件→升级"全流程，可以避免混用 npm/pnpm 导致的 lockfile 漂移与 node_modules 不一致。

七、总结

• Storybook CLI 默认自动探测包管理器，多数情况下无需干预；
• 需要可预期、可复现的安装行为时，用--package-manager <type>强制指定，合法值为源码层面的npm、yarn1、yarn2、pnpm、bun；
• 该参数在 code/lib/create-storybook/src/bin/run.ts 中声明、在 PreflightCheckCommand 中通过force覆盖自动探测结果，语义为"指定安装依赖所用的包管理器"；
• 唯一例外：空目录 + yarn1会被强制回退到 npm；
• 想深究各管理器代理的实现差异，可阅读 code/core/src/common/js-package-manager 目录及其工厂测试 JsPackageManagerFactory.test.ts。