配置系统

相关源文件

• cli/types/cypress-npm-api.d.ts
• cli/types/cypress.d.ts
• cli/types/index.d.ts
• cli/types/tests/cypress-npm-api-test.ts
• cli/types/tests/cypress-tests.ts
• cli/types/tests/kitchen-sink.ts
• packages/app/src/studio/studio-app-types.ts
• packages/server/lib/cloud/protocol.ts
• packages/server/lib/cloud/studio.ts
• packages/server/lib/config.ts
• packages/server/lib/experiments.ts
• packages/server/lib/project-base.ts
• packages/server/lib/project_utils.ts
• packages/server/lib/reporter.js
• packages/server/lib/socket-base.ts
• packages/server/test/support/fixtures/cloud/protocol/test-protocol.ts
• packages/server/test/support/fixtures/cloud/studio/test-studio.ts
• packages/server/test/unit/cloud/protocol_spec.ts
• packages/server/test/unit/cloud/studio_spec.ts
• packages/server/test/unit/config_spec.js
• packages/server/test/unit/open_project_spec.js
• packages/server/test/unit/project_spec.js
• packages/server/test/unit/project_utils_spec.ts
• packages/server/test/unit/reporter_spec.js
• packages/server/test/unit/socket_spec.js
• packages/types/package.json
• packages/types/src/protocol.ts
• packages/types/src/studio/studio-server-types.ts

Cypress 配置系统负责管理 Cypress 架构中测试设置的定义、加载、验证和访问方式。本文档解释了配置在内部如何工作，包括配置文件处理、默认值、验证以及配置如何在应用程序中流动。

有关用户可用的具体配置选项的信息，请参阅公共文档。

概述与架构

配置系统是连接 CLI、服务器和运行器组件的核心组件，它提供了对配置值的统一访问。它负责从多个源加载配置、验证值，并将配置提供给 Cypress 的所有部分。

来源： packages/server/lib/project-base.ts594-644 cli/types/cypress.d.ts475-506

配置生命周期

配置系统遵循从初始化到使用的特定生命周期

来源： packages/server/lib/project-base.ts594-644 packages/server/test/unit/config_spec.js26-162

初始化

配置在 Cypress 项目打开时初始化。 ProjectBase 类通过 initializeConfig 方法处理此问题

来源： packages/server/lib/project-base.ts594-612

配置来源和优先级

Cypress 从多个来源加载配置，并具有特定的优先级顺序

1. 默认值 - Cypress 提供的基础值
2. 配置文件 - 项目根目录下的 cypress.config.{js,ts,mjs,cjs}
3. 环境变量 - 任何以 CYPRESS_ 为前缀的环境变量
4. 环境变量配置文件 - cypress.env.json，用于敏感值
5. 命令行参数 - 传递给 cypress run 或 cypress open 的参数
6. 运行时覆盖 - 在测试中通过 Cypress.config() API 设置的值

来源： packages/server/test/unit/config_spec.js26-162 cli/types/cypress.d.ts475-506

配置数据结构

内部配置对象具有复杂的结构，其中包含特定的属性来跟踪值的来源并提供适当的类型安全。

resolved 对象会跟踪每个配置值的来源，它可以是

• default - Cypress 默认值
• config - 来自 cypress.config.{js,ts}
• env - 来自环境变量
• runtime - 在测试执行期间通过 API 设置

来源： cli/types/cypress.d.ts305-643 packages/server/lib/config.ts7-15

配置访问

Cypress 架构中有多种访问配置值的方式

服务器端访问

在服务器代码中，通过 ProjectBase 类访问配置

来源： packages/server/lib/project-base.ts617-644

客户端（测试）访问

在测试中，通过 Cypress.config() API 访问配置

来源： cli/types/cypress.d.ts475-506 cli/types/tests/cypress-tests.ts30-46

配置验证

Cypress 会验证配置值，以确保它们满足预期的类型和约束。验证系统会检查

1. 类型正确性（例如，数字、字符串、布尔值）
2. 格式正确性（例如，URL 必须以 http:// 或 https:// 开头）
3. 值约束（例如，超时值必须是数字）

当验证失败时，Cypress 会提供详细的错误消息，说明哪里出了问题以及预期是什么。

来源： packages/server/test/unit/config_spec.js106-958

环境变量

以 CYPRESS_ 为前缀的环境变量会自动加载到配置中。前缀会被剥离，其余部分会被转换为 camelCase 以匹配配置属性名。

例如

• CYPRESS_BASE_URL=http://:8080 设置 baseUrl 为 "http://:8080"
• CYPRESS_VIEWPORT_WIDTH=1280 设置 viewportWidth 为 1280

这些值可以通过测试中的 Cypress.env() 访问

来源： cli/types/cypress.d.ts513-538 cli/types/tests/cypress-tests.ts48-56

针对测试类型的特定配置

Cypress 支持两种主要测试类型：端到端（e2e）和组件测试。每种类型在配置文件中都有自己的配置部分。

相应的配置部分会根据当前的测试类型与全局配置合并。

来源： packages/server/test/unit/config_spec.js229-295

配置存储和状态

Cypress 还管理跨运行的持久化状态

保存的状态包括以下信息：

• 项目首次/上次打开时间
• Cypress 应用的用户界面状态
• 显示的提示和横幅

来源： packages/server/lib/project-base.ts645-673 packages/server/test/unit/project_spec.js84-123

运行时配置修改

Cypress 允许在测试执行期间通过 Cypress.config() API 在运行时修改某些配置值。这些更改仅适用于当前测试运行，并且不会在运行之间持久化。

来源： cli/types/tests/cypress-tests.ts862-916

实验功能和功能标志

Cypress 通过 experimentalX 属性使用基于配置的方法来实现实验功能。

来源： packages/server/lib/experiments.ts53-85

配置 API 接口

配置系统为内部和外部使用公开了一个定义明确的 API

来源： cli/types/cypress.d.ts475-538

总结

Cypress 配置系统是管理 Cypress 架构中测试配置的全面框架。它负责从多个源加载、验证、转换，并为应用程序的所有部分提供一致的访问模式。

理解这个系统对于希望自定义测试环境的 Cypress 用户和处理 Cypress 代码库本身的开发人员来说都至关重要。