Cypress 组件测试脚手架引擎（@packages/scaffold-config）源码级解析：框架检测、依赖校验与 `cypress.config.js` 自动生成

组件测试（Component Testing）要让真实的前端工程"开箱即用"，关键一环是在 Cypress Launchpad 引导过程中自动识别项目所用框架与打包器、补齐缺失依赖，并生成一份可直接运行的 cypress.config.js。Cypress 仓库中的 @packages/scaffold-config 正是承担这一职责的脚手架引擎包。本文基于 scaffold-config/README.md 展开，结合其 src 目录 下各模块的 TypeScript 实现、单元测试 以及 system-tests 中的真实示例工程，完整还原其工作原理，并给出"为 Cypress 新增一个框架/库/打包器支持"的落地步骤，让读者既能理解设计思路，也能直接动手扩展。

1. 这个包解决什么问题：scaffold-config 的职责边界

从 README 的第一句可以看出它的定位：@packages/scaffold-config 封装了通过 Launchpad 引导新项目进行组件测试的全部逻辑，包括：

• 检测项目使用的是哪种组件框架（Component Framework）与打包器（Bundler）；
• 安装缺失的依赖；
• 创建开箱即用的 cypress.config.js（必要时还包括 support / commands 文件与组件挂载 HTML 模板）。

仓库对主流代码生成器（Code Generator）产物做了专门适配——例如 create-next-app 生成的 Next.js 应用、Vue CLI 生成的工程——为它们预置"装上就能跑"的 cypress.config.js。同时，对于不是由代码生成器创建、而是手工搭建的 React/Vue + Vite/Webpack 工程，脚手架也会尽力探测出框架与打包器组合并完成配置，这正是源码中 template（模板类框架）与 library（库类框架）两种分类的由来。

该包的代码结构高度内聚，核心文件与职责对应如下：

文件	职责
src/dependencies.ts	声明所有"感兴趣的"依赖：npm 包名、minVersion、安装名、人类可读描述
src/frameworks.ts	内置 CT_FRAMEWORKS 框架定义表、依赖安装检测（isDependencyInstalled）与统一定义解析
src/detect.ts	detectFramework 框架/打包器探测、detectLanguage 配置文件语言（JS/TS）判定
src/ct-detect-third-party.ts	扫描 node_modules 中形如 cypress-ct-* / @scope/cypress-ct-* 的第三方适配器
src/component-index-template.ts	生成组件挂载用 index.html
src/supportFile.ts	生成 support/component.* / support/e2e.*
src/commandFile.ts	生成带注释模板的 commands.* 文件

所有模块经 src/index.ts 汇聚导出，包边界清晰：它只负责"决策与生成"，真正的 dev-server 启动则交给其它包处理。

2. 受支持的框架/库/打包器全景

README 中给出了官方支持的组合矩阵，下面按"框架/打包器/适配器组件/示例工程"重新组织为更清晰的表格（示例工程均可直接在仓库的 system-tests 中查看完整可运行的配置与用例）：

框架	适用构建产物	Dev Server	库版本	组件适配器	可参考的示例工程
React	手工工程	Vite	React 18 / 19	@cypress/react	react-vite-ts-configured
React	手工工程	Webpack	React 18 / 19	@cypress/react	react18、react19
Vue 3	手工工程	Vite	Vue 3	@cypress/vue	vue3-vite-ts-configured
Vue 3	手工工程	Webpack	Vue 3	@cypress/vue	vue3-webpack-ts-configured
Angular	代码生成器（CLI）	Webpack	Angular 21 / 22	@cypress/angular	angular-21、angular-22
Svelte	手工工程	Vite	Svelte 5	@cypress/svelte	svelte-vite-configured
Svelte	手工工程	Webpack	Svelte 5	@cypress/svelte	svelte-webpack-configured
Next.js	代码生成器	Webpack	Next.js 15 / 16（内部使用 React 18/19）	@cypress/react	nextjs-configured

这些定义在源码中并不是写死在某一处"魔法配置"里，而是以结构化数据存在于 src/frameworks.ts 中的 CT_FRAMEWORKS 数组。以 Vue 3 为例，其定义包含了 category、configFramework、detectors（探测依赖）、supportedBundlers、mountModule 等关键字段：

{
  type: 'vue3',
  configFramework: 'vue',
  category: 'library',
  name: 'Vue.js 3',
  detectors: [dependencies.WIZARD_DEPENDENCY_VUE_3],
  supportedBundlers: ['webpack', 'vite'],
  dependencies: (bundler: WizardBundler['type']): Cypress.CypressComponentDependency[] => {
    return [
      getBundler(bundler),
      dependencies.WIZARD_DEPENDENCY_VUE_3,
    ]
  },
  codeGenFramework: 'vue',
  glob: '*.vue',
  mountModule: mountModule('cypress/vue'),
  supportStatus: 'full',
  componentIndexHtml: componentIndexHtmlGenerator(),
}

字段语义（可从 frameworks.ts 与类型定义中读出）：

• category：template 表示"代码生成器产物"（如 Next.js、Angular CLI），这类框架通常锁定唯一打包器；library 表示纯前端库（React/Vue/Svelte），可与多个打包器自由组合；
• detectors：用于判断项目是否属于该框架的探测器依赖，命中即认为使用该框架；
• supportedBundlers：该框架官方支持的打包器集合；
• glob：组件测试默认扫描的 spec 文件匹配模式；
• mountModule：注册 cy.mount() 时从哪个模块导入 mount；
• supportStatus：支持成熟度，见 SUPPORT_STATUSES 定义 ['alpha', 'beta', 'full', 'community']（frameworks.ts#L104）。

生成的配置可直接对照 vue3-vite-ts-configured/cypress.config.ts，这正是"开箱即用"配置的真实形态：

import { defineConfig } from 'cypress'

export default defineConfig({
  component: {
    experimentalSingleTabRunMode: true,
    devServer: {
      framework: 'vue',
      bundler: 'vite',
    },
  },
})

devServer.framework / devServer.bundler 正是由探测结果（见下一节）回填的 configFramework 与所选打包器。

3. 依赖注册中心：每个 npm 包都带有版本门槛与描述

无论是探测还是最终安装，脚手架都依赖一张"依赖清单"。src/dependencies.ts 用 WIZARD_DEPENDENCY_* 常量统一定义，每个依赖对象包含 type、name、package、installer、description 与 minVersion 六个字段，例如：

export const WIZARD_DEPENDENCY_REACT = {
  type: 'react',
  name: 'React.js',
  package: 'react',
  installer: 'react',
  description: 'A JavaScript library for building user interfaces',
  minVersion: '^18.0.0 || ^19.0.0',
} as const

从 dependencies.ts 可整理出当前仓库实际"认可"的版本范围，这与仓库当前实现严格一致：

依赖包	type	minVersion（semver 范围）
webpack	webpack	^5.0.0
vite	vite	^8.0.0
react / react-dom	react / react-dom	`^18.0.0
vue	vue	^3.0.0
svelte	svelte	^5.0.0
next	next	`^15.0.4
@angular/cli、@angular-devkit/build-angular、@angular/core、@angular/common、@angular/platform-browser	angular	`^21.0.0
typescript	typescript	`^5.0.0

值得注意的两个"细节门槛"：

• Next.js 的注释解释了为何起始版本是 ^15.0.4：Next.js 15.0.0~15.0.3 依赖的是 React 19 RC 而非正式版 React 19，Cypress 只支持官方 React 19，因此最低支持线上定为 15.0.4；
• 探测语义使用的是 semver.satisfies(version, minVersion, { includePrerelease: true })（见 frameworks.ts#L72），判定"已安装且版本满足"时才认为依赖就绪。

除了作为安装目标，这张表还用于广谱探测：dependencyNamesToDetect 把组件库（react/vue/svelte/solid-js/preact/lit/ember 等）、打包器（vite/webpack/parcel/rollup/snowpack）以及其它测试库（jest/storybook/testing-library/vitest/playwright 等）的名称汇总成探测候选集合（dependencies.ts#L142-L213）。这样即使某个项目用的是 Cypress 尚未内置支持的库，Launchpad 也能感知到项目技术栈全貌。

4. 探测算法：模板优先、库次之、打包器兜底推断

src/detect.ts 实现了整个探测的核心算法 detectFramework，其决策树与源码注释一致：

1. 先看是不是模板类（template）框架：遍历 category === 'template' 的框架（Next.js、Angular），若其全部探测器依赖都满足且恰好只支持一种打包器，则直接返回该框架 + 唯一的打包器。源码注释特别说明：之所以要求"唯一打包器"，是考虑到未来像 Nuxt 这类工具会同时提供 webpack 与 vite 两种 dev-server，届时还需额外推断用户选择。
2. 再看是不是库类（library）框架：遍历 category === 'library' 的框架，先确认库依赖满足（例如项目里有 React），再依次用 WIZARD_BUNDLERS（webpack、vite）做二次探测：
   • 命中某个打包器 → 返回 { framework, bundler } 组合；
   • 库命中但打包器未知 → 只返回 framework，打包器选择权交给用户在 Launchpad 中手动决定；
3. 都不命中 → 返回空结果，交给用户手工选择。

每次探测最终都落到 frameworks.ts 中的 isDependencyInstalled：通过 resolve-package-path 在目标项目解析包并读取其 package.json，返回 { dependency, detectedVersion, satisfied } 三元组；任何解析失败都只会导致 satisfied: false，而不会中断整个流程——这一点保证了对未安装依赖项目的友好性。其姊妹函数 isDependencyInstalledByName 则只关心"装没装、版本多少"，不参与 semver 满足性判断。

4.1 配置文件语言检测：JS 还是 TS

生成 cypress.config.*、support 与 commands 文件前，还需要确定语言。detectLanguage 按源码注释中的决策表执行：

• 存在自定义 Cypress 配置文件时：按扩展名判定，.ts/.mts → TS，.js/.cjs/.mjs → JS；
• 否则检查工程根目录是否存在默认 cypress.config.ts|mts / cypress.config.js|cjs|mjs；
• 若项目里根本没装 TypeScript，直接回退 JS（注释解释了原因：类型检查没法在后续安装流程中工作）；
• package.json 的 dependencies 或 devDependencies 中出现 typescript → TS；
• 再用 globby 扫描 cypress/**/*.{ts,tsx}（剔除 .d.ts）与 **/*tsconfig.json，发现真实 TS 源码 → TS；
• 全部未命中 → 默认 JS。

这套规则保证了生成的配置与用户既有工程的语言习惯保持一致，避免"TS 项目被塞一份 JS 配置"这类体验割裂。

5. 第三方组件测试适配器：cypress-ct-* 生态如何接入

除了内置框架，Cypress 还开放了第三方适配器机制，让社区/企业内部库（如 Solid.js）无需合入核心也能被 Launchpad 识别。src/ct-detect-third-party.ts 承担这项工作，其关键行为包括：

• 命名约定：包类型必须满足 cypress-ct-*（全局）或 @scope/cypress-ct-*（命名空间）两种前缀规则，由 isThirdPartyDefinition 判断（ct-detect-third-party.ts#L85-L88）；
• 扫描范围：从工程根目录开始沿祖先目录向上查找 node_modules/cypress-ct-*/package.json 与 node_modules/@*?/cypress-ct-*?/package.json，直到识别出"仓库根"为止。isRepositoryRoot 通过检查 .git、pnpm-workspace.yaml、rush.json、workspace.json、nx.json、lerna.json 或含 workspaces 字段的 package.json 来判断（ct-detect-third-party.ts#L28-L83），因此也兼容 pnpm workspace、Lerna、Nx、Rush 等 monorepo 布局；
• 解析与校验：用 require.resolve(pkg.name, { paths: [projectRoot] }) 解析模块入口（源码注释解释了为何不能用绝对路径解析：会绕过 package.json 的 exports 字段），加载后用 zod schema ThirdPartyComponentFrameworkSchema 校验其导出结构，校验失败的模块进入 erroredFrameworks 列表而不是抛错中断；
• 统一化：第三方定义在 resolveComponentFrameworkDefinition 中被归一化为与内置框架同构的 ResolvedComponentFrameworkDefinition——被强制归类为 library、supportStatus: 'community'，且打包器依赖会按用户在 Launchpad 中的选择自动追加。

测试桩 test/fixtures.ts 提供了一个标准示例：包名为 cypress-ct-solid-js、通过 defineComponentFramework 导出（源码注释强调必须是 default export），detectors 声明 solid-js ^1.0.0，supportedBundlers 支持 webpack 与 vite。对应单元测试位于 test/ct-detect-third-party.spec.ts，端到端示例可参考 system-tests 下的 ct-public-api-solid-js。

6. 脚手架会生成哪些文件：从 mount 注册到 HTML 模板

探测并安装依赖后，脚手架需要生成能让测试真正跑起来的工程文件。生成器按"语言 × 用途"组合产出模板文本，全部可在 src/ 源码中逐字查看：

• supportFile.ts：supportFileE2E(language) 生成 e2e 用的 support/e2e.js|ts；supportFileComponent(language, mountModule) 生成组件测试用的 support/component.js|ts。对组件测试，无论 JS 还是 TS，都会注入 import { mount } from '<mountModule>' 与 Cypress.Commands.add('mount', mount)；TS 变体额外以 declare global 增强 Cypress.Chainable 命名空间（也可改放 component.d.ts），并附带 cy.mount(<MyComponent />) 之类的示例注释。
• commandFile.ts：生成示例 commands.*，内嵌注释演示 Cypress.Commands.add 的 parent/child/dual command 与 overwrite 用法；TS 变体在文件头加 /// <reference types="cypress" />，文件尾附一段被注释包裹的 declare global 类型示例。
• component-index-template.ts：通过 componentIndexHtmlGenerator(headModifier) 生成 index.html，内含 data-cy-root 挂载节点与移动端 viewport meta。headModifier 参数允许框架注入自定义 head 内容——例如 Next.js 定义中传入 <div id="__next_css__DO_NOT_USE__"></div>（其注释链接到 Next.js 源码：该 div 供 Next 通过 style-loader 注入 CSS 使用），这是"模板差异化"最直观的体现。

这些生成器的逐文件断言测试位于 packages/scaffold-config/test（如 supportFile.spec.ts、commandFile 相关、component-index-template.spec.ts、dependencies.spec.ts、frameworks.spec.ts、detect.spec.ts），它们以快照/断言方式锁定输出文本，是改动生成逻辑时的第一道防线。

7. 如何为 Cypress 新增一套框架支持（官方步骤）

README 给出了加入新库/框架/打包器支持的完整流程，共 6 步，此处逐条展开并结合仓库现状说明每一步的落点与验证方式：

1. 在 src/frameworks.ts 注册框架定义。仿照既有条目在 CT_FRAMEWORKS 中加入新对象，正确填写 category、detectors、supportedBundlers、dependencies(bundler)、mountModule、glob、componentIndexHtml 等字段；若是第三方库且未合入核心，则按第 5 节的方式以 cypress-ct-* 包形式发布。

2. 在 src/dependencies.ts 声明所有新依赖，且必须补 description 字段。新增 WIZARD_DEPENDENCY_* 常量时，除 npm 包名、minVersion 外，务必填写一段面向用户展示的描述文本——这个字段会在 Launchpad 的依赖安装步骤中直接展示，缺了它会破坏用户体验。不要忘了把依赖追加进 WIZARD_DEPENDENCIES 聚合数组，必要时同步更新 dependencyNamesToDetect。

3. 在 test/detect.spec.ts 增加单元测试，确保项目能被正确识别出"库 + 打包器"组合（README 原文要求：Ensure your project has the correct library and bundler detected）。这是第一层、也是成本最低的回归保护。

4. 在 system-tests/projects 下新增 <name>-configured 工程，内含正确的 cypress.config.js/package.json 与若干真实 spec，即"装好 Cypress 后的理想最终状态"；随后在 component_testing_spec.ts 中注册，确保它能在 CI 上跑通组件测试。仓库里 react-vite-ts-configured、nextjs-configured、svelte-vite-configured 等即此类工程的现成范本。

5. 再新增一个 <name>-unconfigured 工程，代表"尚未接入 Cypress 的原始项目"（如 react-vite-ts-unconfigured、vue3-webpack-ts-unconfigured、nextjs-unconfigured），它专门用于下一步的端到端验证。

6. 在 scaffold-component-testing.cy.ts 增加端到端用例，驱动真实 Launchpad 对着 <name>-unconfigured 工程执行引导，断言最终生成的 cypress.config.js 内容正确。README 建议直接以既有测试为模板改写，这正是"配置生成是否正确"的最高级别验证。

8. 打包与内部测试注意事项

README 的最后一部分澄清了两个容易踩坑的工程化事实：

• @packages/scaffold-config/browser/dependencies 不参与生产构建。这部分代码仅供内部测试使用，不属于生产 binary，因此包在 bundle 阶段无需包含它。这与 tsconfig.browser.json、vitest.config.ts 等构建配置共同描述了包在不同目标环境下的裁剪边界。
• ESM 版本已构建但暂未启用。仓库会构建一份 @packages/scaffold-config 的 ESM 产物，但该包当前实际只在服务端以 CommonJS 方式被引用，所以 ESM 产物尚未接入运行时。这提醒改动者：同时维护 tsconfig.cjs.json 与 tsconfig.esm.json 两套编译配置时，要注意产物一致性，避免引入只在一侧生效的语法特性。

总结

@packages/scaffold-config 是 Cypress 组件测试体验的"接线员"：它以结构化框架定义（CT_FRAMEWORKS）+ 依赖注册表（WIZARD_DEPENDENCY_*）为数据源，用模板优先/库次之的探测算法与基于文件扩展名、包清单和源码扫描的语言判定，配合对 cypress-ct-* 第三方适配器的自动发现，最终落成一份开箱即用的 cypress.config.js 及配套 support/commands/index.html 文件。理解这套机制的收益有两层：对使用者，能解释"为什么 Launchpad 能认出我的 Next.js/Vue/React 工程"并预判兼容边界；对二次开发者，则能从框架定义 → 依赖声明 → 单元测试 → system-tests 示例工程 → Launchpad 端到端测试的完整链路中，找到为 Cypress 添加新框架支持时的每一步落点。