Cypress组件测试需满足四条件：≥v10.0.0版本、cypress.config.js启用component且含setupNodeEvents、安装对应框架适配器并注册、VSCode用官方调试配置。
VSCode里跑不起来cypress open，是不是没装对插件？
不是插件问题，是Cypress本身没被识别为可执行命令。VSCode终端默认不继承系统PATH里的Node全局bin路径（比如npx或全局安装的cypress），所以直接输cypress open会报command not found。
实操建议：
- 优先用
npx cypress open——只要项目根目录有cypress依赖（package.json里有"cypress"），就一定能跑起来 - 别全局安装
cypress：版本容易和项目不一致，cypress open启动时可能报Cannot find module 'cypress' - 确认
cypress在devDependencies里，且已运行过npm install或yarn install
组件测试文件写好了，但cypress open里看不到Component Testing标签页
Cypress 10+才原生支持组件测试，但默认只启用E2E模式。没看到标签页，说明配置缺失或版本不匹配。
实操建议：
- 检查Cypress版本：
npx cypress --version，必须≥10.0.0；低于这个版本压根不支持component模式 - 项目根目录加
cypress.config.js，内容至少包含component: { enabled: true } -
cypress.config.js里不能漏掉setupNodeEvents——哪怕空函数也要写，否则Vite/React/Vue的预处理器加载失败 - 确保
cypress文件夹下有components子目录（不是integration），且里面放的是*.spec.tsx这类文件
点开Component Testing后白屏，控制台报Failed to fetch或Cannot find module '@cypress/react'
组件测试不是“开箱即用”，它依赖框架适配器（比如@cypress/react或@cypress/vue），而且必须手动注册到测试入口。
实操建议：
- 按框架装对应包：
npm install -D @cypress/react（React）或@cypress/vue（Vue 3），别只装cypress - 在
cypress/support/component.ts里显式导入并注册：import '@cypress/react'（React）或import '@cypress/vue'（Vue） - 检查
cypress.config.js中component配置是否指定了正确的devServer：{ framework: 'react', bundler: 'vite' }这类字段必须和项目实际一致 - 如果用Vite，确保
vite.config.ts里没禁用resolve.alias——Cypress组件测试依赖别名解析JSX/TSX
断点调试cy.mount()里的组件逻辑，VSCode里F5没反应
VSCode默认调试配置不认识Cypress组件测试的运行时环境，launch.json不配对，断点就只是红点，不触发暂停。
实操建议：
- 删掉所有自定义
launch.json，改用Cypress官方推荐的“自动配置”：Ctrl+Shift+P→ 输入Cypress: Configure VS Code Debugger→ 选Component Testing - 确保VSCode用了最新版Cypress插件（
Cypress Helper），旧版不支持cy.mount()源码映射 - 断点只能打在组件源码（比如
Button.tsx）里，不能打在cy.mount()调用行或it()块里——那些是Cypress运行时代码，没映射回源文件 - 第一次调试前，先在UI里点一次组件测试用例，让Cypress启动dev server；否则VSCode连不上调试端口
组件测试的调试链路比E2E长一截：Vite dev server → Cypress test runner → Chrome renderer → 源码sourcemap。任何一环断开，断点就失效，但问题通常出在配置没对齐，而不是代码本身。
