Storybook 崩溃报告遥测：使用 --enable-crash-reports 标志与三种启用方式详解-编程实验室

Storybook 崩溃报告遥测：使用 --enable-crash-reports 标志与三种启用方式详解

【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook

Storybook 默认收集完全匿名的使用数据以改进开发者体验，而崩溃报告（Crash Reports）默认处于关闭状态，需要显式开启才会随遥测事件上报错误堆栈。本指南围绕--enable-crash-reports命令行标志，完整讲解如何在 npm、pnpm、yarn 三种包管理器下通过 CLI 启用崩溃报告，并深入其背后的配置项（enableCrashReports）、环境变量（STORYBOOK_ENABLE_CRASH_REPORTS）与源码级脱敏机制。读完后，你将能在团队项目中按需打开或彻底关闭崩溃上报，同时理解错误信息是如何被匿名化保护隐私的。

崩溃报告与常规遥测的区别

Storybook 的遥测系统由两部分组成（官方文档见 docs/configure/telemetry.mdx）：

常规使用遥测（默认开启）：记录命令调用（如init、upgrade、dev、build）、Storybook 版本、addons、视图层（view layer）、包管理器、monorepo 信息等汇总性数据；
崩溃报告（默认关闭）：在常规遥测之上，额外将脱敏后的错误对象（sanitized error）附加到遥测事件中，帮助维护团队定位真实崩溃原因。

二者的关系用一句源码注释可以概括：在 code/core/src/telemetry/index.ts 中，只有当options?.enableCrashReports为真时，才会把完整错误对象写入事件载荷；否则错误只在常规遥测中以消息摘要形式出现。

通过命令行标志启用：--enable-crash-reports

关联文档 docs/_snippets/storybook-telemetry-storybook-enable-crash-reports-flag.md 给出了三种包管理器下启用崩溃报告的标准命令，直接复用于storybookCLI：

npm run storybook -- --enable-crash-reports

pnpm run storybook --enable-crash-reports

yarn storybook --enable-crash-reports

使用要点：

npm 需要--分隔符：npm run storybook会把参数透传给脚本，因此必须用--把--enable-crash-reports转交给实际的storybook命令；
pnpm 无需--：pnpm 默认将run之后的参数直接透传给脚本；
yarn 直接调用：yarn storybook直接执行二进制，标志自然生效。

该标志对所有 storybook CLI 子命令均有效。在 docs/api/cli-options.mdx 中，--enable-crash-reports被声明为"向 Storybook 遥测发送崩溃报告"的通用选项，覆盖了storybook dev、storybook build、storybook init、storybook remove、storybook upgrade、storybook automigrate、storybook sandbox以及create storybook等全部命令，例如：

storybook dev --enable-crash-reports storybook build --enable-crash-reports storybook upgrade --enable-crash-reports

也就是说，无论在开发、构建还是升级阶段遇到问题，都可以临时加上该标志上报崩溃，便于维护团队复现和修复。

另外两种等价的启用方式

除了 CLI 标志，崩溃报告还有两种配置入口，三者效果等价、可任选其一：

方式一：配置文件中的`enableCrashReports`

在 Storybook 的main.js|ts配置文件中，将core.enableCrashReports设为true（参考 docs/api/main-config/main-config-core.mdx 中该选项的说明，类型为boolean）：

// .storybook/main.js export default { core: { enableCrashReports: true, }, };

该选项与core.disableTelemetry同属core命名空间。在源码层面，code/core/src/core-server/presets/common-preset.ts 与 code/core/src/types/modules/core-common.ts 负责承载这一配置，并最终映射到遥测系统的Options.enableCrashReports（见 code/core/src/telemetry/types.ts 中的Options接口定义）。

方式二：环境变量`STORYBOOK_ENABLE_CRASH_REPORTS`

将环境变量设为1即可：

STORYBOOK_ENABLE_CRASH_REPORTS=1 storybook dev

对于 CI/CD 流水线等不便改配置文件的场景，环境变量是最轻量的开关。

底层原理：错误级别解析与脱敏上报

启用崩溃报告后，实际发送流程由 code/core/src/core-server/withTelemetry.ts 驱动。核心函数getErrorLevel按优先级决定错误上报级别（'none' | 'error' | 'full'）：

若cliOptions.disableTelemetry为真，直接返回'none'（遥测整体关闭）；
加载 presets 后读取main.js中的core.enableCrashReports：为true返回'full'（发送完整错误），为false返回'error'（仅发送错误摘要）；core.disableTelemetry为真则返回'none'；
读取缓存中的历史选择（兼容旧版enableCrashreports拼写）；
非 TTY 或 CI 环境下跳过交互，直接返回'error'；
否则弹出交互式确认（"Would you like to send anonymous crash reports to improve Storybook and fix bugs faster?"），把选择写入缓存。

只有errorLevel === 'full'时，sendTelemetryError才会以enableCrashReports: true且force: true的方式调用telemetry('error', ...)——force选项的意义在 code/core/src/telemetry/index.ts 中有注释说明："用于启用崩溃报告时的错误遥测，绕过禁用状态"。这意味着即使常规遥测被关闭，只要显式开启了崩溃报告，错误事件仍会发送。

错误脱敏：$SNIP 替换用户路径

崩溃报告发送前，错误对象会经过 code/core/src/telemetry/sanitize.ts 的sanitizeError处理，其核心逻辑是：

removeAnsiEscapeCodes：剥离错误消息与堆栈中的 ANSI 颜色转义码；
cleanPaths：基于process.cwd()与os.homedir()逐级向上泛化路径，把所有用户相关的绝对路径（含 Windows 双分隔符变体）替换为$SNIP占位符。

因此崩溃报告中不会出现开发者的真实目录结构。官方文档 docs/configure/telemetry.mdx 给出的崩溃报告事件示例（对应片段 docs/_snippets/storybook-telemetry-crash-report-event.md）展示了脱敏后的效果：

{ stack: 'Error: Your button is not working\n' + ' at Object.<anonymous> ($SNIP/test.js:39:27)\n' + ' at Module._compile (node:internal/modules/cjs/loader:1103:14)\n' + ' ...', message: 'Your button is not working' }

可见用户路径已被$SNIP遮蔽，仅保留错误本身与 Node 内部栈帧，既可用于调试又不泄露本地文件布局。文档同时强调，可通过设置STORYBOOK_TELEMETRY_DEBUG=1在本地打印所有将要收集的信息，做到完全透明可审计。

如何关闭遥测与崩溃报告

崩溃报告依赖遥测通道，因此关闭遥测即同时关闭崩溃上报。官方提供三种方式（见 docs/configure/telemetry.mdx 的 "How to opt-out" 一节）：

// 1. main.js 配置 export default { core: { disableTelemetry: true, }, };

# 2. CLI 标志 storybook dev --disable-telemetry

# 3. 环境变量 STORYBOOK_DISABLE_TELEMETRY=1 storybook dev

需要注意一个细节：存在一个不携带任何元数据的boot事件，它用于确认遥测通道可用，且在评估main.js之前就已发送，因此不受disableTelemetry配置影响；若希望连这个事件也不发送，必须使用STORYBOOK_DISABLE_TELEMETRY环境变量。从 code/core/src/core-server/withTelemetry.ts 的resolveTelemetryState可以看出，CLI 选项与main.js配置都会在加载 presets 之前或之后被显式读取并决定遥测开关状态。

小结

启用崩溃报告：npm run storybook -- --enable-crash-reports（npm）、pnpm run storybook --enable-crash-reports（pnpm）、yarn storybook --enable-crash-reports（yarn），该标志适用于dev、build、init、upgrade等所有 CLI 子命令；
等价配置：core.enableCrashReports: true或环境变量STORYBOOK_ENABLE_CRASH_REPORTS=1；
隐私保障：错误对象经 sanitize.ts 脱敏，用户路径一律替换为$SNIP，可用STORYBOOK_TELEMETRY_DEBUG=1本地核验；
彻底关闭：core.disableTelemetry: true、--disable-telemetry或STORYBOOK_DISABLE_TELEMETRY=1。

崩溃报告是默认关闭的可选项，适合在遇到难以复现的 CLI 崩溃时临时开启，将匿名错误堆栈反馈给维护团队；而日常开发中，保持默认关闭或按团队隐私策略显式配置即可。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Storybook 崩溃报告遥测：使用 --enable-crash-reports 标志与三种启用方式详解