Skip to main content
Cypress应用

安装 Cypress

info
你将学到​
  • 如何使用 npm、Yarn 或 pnpm 安装 Cypress
  • Cypress 的系统要求
  • 如何通过直接下载安装 Cypress
  • 高级安装选项

安装 Cypress

首先，请确保满足 系统要求，包括 操作系统、 安装 Node.js 和 支持的 包管理器。

安装​

通过你首选的 包管理器 安装 Cypress。 这将把 Cypress 作为开发依赖项安装到你的项目中。

npm install cypress --save-dev

在安装 Cypress 之前，请确保项目根目录中有 package.json 文件。 如果需要创建该文件， 可以运行你的 包管理器 的 init 命令。

系统 代理属性 http_proxy、https_proxy 和 no_proxy 会 影响 Cypress 二进制文件的下载。 你也可以使用 npm 属性 npm_config_proxy 和 npm_config_https_proxy。 这些属性的优先级较低，因此 只有在系统属性解析为不使用代理时才会生效。

直接下载​

推荐的方法是使用 npm 安装 Cypress，因为：

  • Cypress 像其他依赖项一样进行版本管理。
  • 它简化了在 持续集成 中运行 Cypress 的过程。

如果你的项目没有使用 Node 或包管理器，或者你只是想快速试用 Cypress， 你可以 直接从我们的 CDN 下载 Cypress。

caution

直接下载的版本无法将运行记录到 Cypress Cloud。 此下载仅用于快速试用 Cypress。要将测试记录到 Cypress Cloud，你需要将 Cypress 作为包依赖项安装。

直接下载将始终获取最新可用版本。你的平台 会自动检测。

然后你可以手动解压并双击运行。Cypress 无需安装 任何依赖即可运行。

info
下载旧版本

可以通过在 URL 后附加所需版本号来下载旧版本（例如 https://download.cypress.io/desktop/12.17.4）。

高级安装​

如果你有更复杂的需求，想要提升 Cypress 工作流程或 需要故障排除帮助，请查看我们的 高级安装 参考。 你还可以在此参考文档中找到 卸载 Cypress 的说明。

持续集成​

请阅读我们的 持续集成 文档以获取 在 CI 中安装 Cypress 的帮助。在 Linux 中运行时，你可能需要安装一些 系统依赖项 或使用我们的 Docker 镜像，这些镜像已预装所有必要内容。

系统要求​

操作系统​

Cypress 支持在以下操作系统上运行：

  • macOS 11 及以上版本 (Intel 或 Apple Silicon 64 位 (x64 或 arm64))
  • Linux (x64 或 arm64) 另请参阅下方的 Linux 先决条件
    • Ubuntu 20.04 及以上版本
    • Debian 11 及以上版本
    • Fedora 41 及以上版本
  • Windows 10 和 11 (x64)
  • Windows 11 24H2 (arm64，在 x64 模拟模式 下运行，最低需要 Cypress 14.5.0) - 预览状态
  • Windows Server 2019、2022 和 2025 (x64)

Node.js​

Cypress 需要 Node.js 才能安装。我们支持以下版本：

  • Node.js 18.x、20.x、22.x 及以上版本

Cypress 通常与 Node 的发布计划 保持一致。 因此，使用 Node.js 18 和 23 与 Cypress 已被弃用，并计划在未来的 Cypress 版本中移除支持。

安装 Node.js​

按照 下载 Node.js 上的说明下载并安装 Node.js。

tip
最佳实践

使用 下载 Node.js 上建议的 Node.js 版本管理器安装 Node.js， 或使用你选择的其他 Node.js 版本管理器。 这样可以轻松切换不同版本的 Node.js。

请注意，不推荐将 Node.js Snap for Linux 版本管理器与 Cypress 一起使用。 尝试以非 root 用户身份使用可能会导致权限错误。

如果你使用的是 Cypress Docker 镜像， 你会发现镜像中已预装了固定版本的 Node.js。 你可以通过 Docker 镜像标签选择 Node.js 版本。

包管理器​

Cypress 使用以下支持的包管理器之一进行 安装：

包管理器版本安装说明
npm8.6.0 及以上下载并安装 Node.js 和 npm
Yarn 1 (Classic)1.22.22 及以上Yarn 1 (Classic) 安装
Yarn (Modern aka berry)4.x 及以上Yarn 安装
pnpm8.x 及以上pnpm 安装

Yarn 配置​

推荐使用 Yarn (Modern) 配置 nodeLinker: "node-modules"。 Cypress 组件测试 目前与默认设置 nodeLinker: "pnp" 不兼容，该设置使用 Yarn Plug'n'Play。

pnpm 配置​

以下配置选项使 Cypress 能够执行其 postinstall 脚本，从而将 Cypress 二进制文件安装到 二进制缓存 中。 如果未设置这些配置选项，Cypress 可能会跳过 postinstall 脚本的执行，从而导致无法运行。

pnpm 的 副作用缓存 使用并缓存 (pre/post)install 钩子的结果，与 Cypress 自身的缓存不兼容。 禁用 pnpm 的 副作用缓存，例如在 Cypress 项目的根目录中执行以下命令：

pnpm config set side-effects-cache false --location project

pnpm@10.0.0 及以上版本需要将 cypress 加入白名单。 有关更多信息，请参阅 pnpm 设置 文档。 在 pnpm@10.4.0 及以上版本中，可以使用 CLI add 选项 --allow-build，例如：

pnpm --allow-build=cypress add --save-dev cypress

硬件​

在本地运行 Cypress 时，它应该可以在任何能够进行现代 Web 开发的机器上流畅运行。

然而，在 CI 中运行 Cypress 时，一些低端配置可能无法可靠地运行 Cypress， 尤其是在录制视频或进行较长测试运行时。

在 CI 中可能会遇到的一些问题可能是资源不足的迹象：

  • 在 cypress run 期间提前退出或突然关闭（“崩溃”）
  • 捕获的视频中出现冻结或缺失的帧
  • 运行时间增加

在 CI 中运行 Cypress 时，我们建议满足以下硬件要求：

CPU​

  • 至少 2 个 CPU 来运行 Cypress
  • 如果启用了视频录制，则需要额外 1 个 CPU
  • 每个在 Cypress 之外运行的进程需要额外 1 个 CPU，例如：
    • 应用服务器（前端）
    • 应用服务器（后端）
    • 应用数据库
    • 任何其他基础设施（Redis、Kafka 等）

内存​

  • 最少 4GB，较长测试运行需要 8GB 及以上

Linux 先决条件​

如果你使用的是 Linux，你需要在系统上安装必要的依赖项。 根据系统默认设置，这些依赖项可能已经安装。 如果未安装，请运行下面列出的适用于你操作系统的命令行。 有关 Cypress Docker 镜像 的信息，请参阅下方的 Docker 先决条件。这些镜像已包含所有必要的依赖项。

Ubuntu/Debian​

apt-get install libgtk2.0-0 libgtk-3-0 libgbm-dev libnotify-dev libnss3 libxss1 libasound2 libxtst6 xauth xvfb

对于 Ubuntu 24.04 及以上版本，使用以下命令：

apt-get install libgtk2.0-0t64 libgtk-3-0t64 libgbm-dev libnotify-dev libnss3 libxss1 libasound2t64 libxtst6 xauth xvfb

Arch​

pacman -S gtk2 gtk3 alsa-lib xorg-server-xvfb libxss nss libnotify

Amazon Linux 2023​

dnf install -y xorg-x11-server-Xvfb gtk3-devel nss alsa-lib

Docker 先决条件​

Cypress Docker 镜像 可从 Docker Hub 和 Amazon ECR (Elastic Container Registry) Public Gallery 获取。 这些基于 Linux (Debian) 的镜像已预装所有必要的依赖项。

如果你需要的 Node.js、浏览器或 Cypress 版本组合不在已发布的 Cypress Docker 镜像中， 那么 cypress/factory 镜像 可以让你轻松生成自定义的 Docker 镜像。

如果你不使用 Cypress Docker 镜像，请确保你的基础操作系统是上述支持的 操作系统 之一，并且镜像中已安装 Node.js。 建议安装 unzip。这样可以避免 Cypress 二进制文件安装回退到使用 Node.js 的较慢解压方法。

下一步​

打开应用 并试用吧！

目录