Cypress应用

高级安装

info

你将学到

如何通过自定义二进制文件安装Cypress
如何跳过Cypress二进制文件安装
如何更改Cypress二进制缓存位置或下载URL
如何使用自定义证书颁发机构(CA)
如何选择不向Cypress发送异常数据

环境变量

名称	描述
`CYPRESS_INSTALL_BINARY`	指定下载和安装的Cypress二进制文件目标位置
`CYPRESS_CONNECT_RETRY_THRESHOLD`	覆盖连接浏览器时的最大重试次数。默认值为62。
`CYPRESS_DOWNLOAD_MIRROR`	通过镜像服务器下载Cypress二进制文件
`CYPRESS_DOWNLOAD_PATH_TEMPLATE`	允许生成自定义URL来下载Cypress二进制文件
`CYPRESS_CACHE_FOLDER`	更改Cypress二进制缓存位置
`CYPRESS_RUN_BINARY`	运行时Cypress二进制文件的位置
`CYPRESS_VERIFY_TIMEOUT`	覆盖`verify`命令的超时时间。默认值为30000。
`CYPRESS_SKIP_VERIFY`	当值为`true`时跳过`verify`命令
~~CYPRESS_SKIP_BINARY_INSTALL~~	已移除改用`CYPRESS_INSTALL_BINARY=0`
~~CYPRESS_BINARY_VERSION~~	已移除改用`CYPRESS_INSTALL_BINARY`

安装二进制文件

使用CYPRESS_INSTALL_BINARY环境变量，你可以控制Cypress的安装方式。要覆盖默认安装内容，可以在npm install命令旁设置CYPRESS_INSTALL_BINARY。

这在以下情况下很有用：

安装与默认npm包不同的版本。

CYPRESS_INSTALL_BINARY=13.7.0 npm install cypress@13.7.1

指定外部URL（绕过企业防火墙）。

CYPRESS_INSTALL_BINARY=https://company.domain.com/cypress.zip npm install cypress

指定本地文件而非从互联网安装。

CYPRESS_INSTALL_BINARY=/local/path/to/cypress.zip npm install cypress

在所有情况下，从自定义位置安装二进制文件的事实_不会保存在你的package.json文件中_。每次重复安装都需要使用相同的环境变量来安装相同的二进制文件。

跳过安装

你也可以通过设置CYPRESS_INSTALL_BINARY=0强制Cypress跳过二进制应用程序的安装。这在你想阻止Cypress在npm install时下载Cypress二进制文件的情况下很有用。

CYPRESS_INSTALL_BINARY=0 npm install

现在Cypress将在npm模块安装完成后跳过其安装阶段。

安装问题排查

Cypress的生命周期脚本postinstall会在Cypress npm模块安装后安装Cypress二进制文件。然而，包管理器默认在后台执行postinstall步骤，这会隐藏调试输出。单独执行cypress install并启用调试日志以查看调试日志。

npm
Yarn
pnpm

CYPRESS_INSTALL_BINARY=0 npm install cypress --save-dev
DEBUG=cypress:cli* npx cypress install

CYPRESS_INSTALL_BINARY=0 yarn add cypress --dev
DEBUG=cypress:cli* yarn cypress install

CYPRESS_INSTALL_BINARY=0 pnpm add --save-dev cypress
DEBUG=cypress:cli* pnpm cypress install

要在Windows CMD或PowerShell终端中设置环境变量CYPRESS_INSTALL_BINARY和DEBUG，请参考打印DEBUG日志中的示例。

在持续集成(CI)环境中，使用以下命令显示Cypress二进制文件安装的调试日志：

npm
Yarn
pnpm

DEBUG=cypress:cli* npm ci --foreground-scripts

yarn install --frozen-lockfile --ignore-scripts # 仅限Yarn v1 Classic
DEBUG=cypress:cli* yarn cypress install

pnpm install --frozen-lockfile --ignore-scripts
DEBUG=cypress:cli* pnpm cypress install

二进制缓存

Cypress将匹配的Cypress二进制文件下载到全局系统缓存中，以便在项目之间共享二进制文件。默认的全局缓存文件夹为：

MacOS: ~/Library/Caches/Cypress
Linux: ~/.cache/Cypress
Windows: /AppData/Local/Cypress/Cache

要覆盖默认缓存文件夹，请设置环境变量CYPRESS_CACHE_FOLDER。

CYPRESS_CACHE_FOLDER=~/Desktop/cypress_cache npm install

CYPRESS_CACHE_FOLDER=~/Desktop/cypress_cache npm run test

Cypress会自动将~替换为用户的主目录。因此你可以从CI配置文件中传递CYPRESS_CACHE_FOLDER作为字符串，例如：

environment:
  CYPRESS_CACHE_FOLDER: '~/.cache/Cypress'

另请参阅文档中的持续集成 - 缓存部分。

caution

每次启动Cypress时，CYPRESS_CACHE_FOLDER必须存在。为确保这一点，请考虑导出此环境变量。例如，在.bash_profile（MacOS、Linux）中或使用RegEdit（Windows）。

运行二进制文件

设置环境变量CYPRESS_RUN_BINARY可以覆盖npm模块查找Cypress二进制文件的位置。

CYPRESS_RUN_BINARY应指向已解压的Cypress二进制可执行文件的路径。Cypress命令open、run和verify将随后启动提供的二进制文件。

以下cypress run命令示例假设你已先将Cypress二进制文件下载到操作系统的默认Downloads目录。

根据你随后解压下载的Cypress二进制文件cypress.zip的方式（使用CLI命令或GUI界面），目录结构可能包含一个额外的顶级目录cypress，你可能需要将其添加到CYPRESS_RUN_BINARY定义的路径中。

如果可用，请使用以下命令以避免额外的顶级目录级别：

unzip -q cypress

note

以下示例适用于npm。如果你使用Yarn或pnpm作为包管理器，请将npx替换为yarn或pnpm。参见如何运行命令。

Mac

CYPRESS_RUN_BINARY=~/Downloads/Cypress.app/Contents/MacOS/Cypress npx cypress run

Linux

CYPRESS_RUN_BINARY=~/Downloads/Cypress/Cypress npx cypress run

Windows

CYPRESS_RUN_BINARY=~/Downloads/Cypress/Cypress.exe npx cypress run

tip

Cypress假设CYPRESS_RUN_BINARY指向一个可写的目录结构，以便它可以保存并重复使用验证Cypress二进制文件的结果。如果你遇到cypress verify的permission denied失败消息，你可以通过将环境变量CYPRESS_SKIP_VERIFY设置为true来绕过此失败。

下载URL

如果你想为特定平台（操作系统）下载特定版本的Cypress，可以从我们的CDN获取。

下载服务器URL为https://download.cypress.io。

目前我们提供以下下载：

Windows 64位 (?platform=win32&arch=x64)
Linux 64位 (?platform=linux)
macOS 64位 (?platform=darwin)

以下是可用的下载URL：

查看https://download.cypress.io/desktop.json获取所有可用平台。

方法	URL	描述
`GET`	`/desktop`	下载最新版本的Cypress（平台自动检测）
`GET`	`/desktop.json`	返回包含最新可用CDN目标的JSON
`GET`	`/desktop?platform=p&arch=a`	下载特定平台和/或架构的Cypress
`GET`	`/desktop/:version`	下载指定版本的Cypress
`GET`	`/desktop/:version?platform=p&arch=a`	下载指定版本、平台和/或架构的Cypress

下载Windows 64位Cypress 12.17.4的示例：

https://download.cypress.io/desktop/12.17.4?platform=win32&arch=x64

镜像

如果你选择镜像整个Cypress下载站点，可以指定CYPRESS_DOWNLOAD_MIRROR将下载服务器URL从https://download.cypress.io更改为你自己的镜像。

例如：

CYPRESS_DOWNLOAD_MIRROR="https://www.example.com" cypress install

Cypress随后将尝试以下格式下载二进制文件： https://www.example.com/desktop/:version?platform=p

下载路径模板

从Cypress 9.3.0开始，你可以使用CYPRESS_DOWNLOAD_PATH_TEMPLATE环境变量根据端点、版本、平台和架构从自定义URL下载Cypress二进制文件。

支持以下替换：

${endpoint}替换为https://download.cypress.io/desktop/:version。如果设置了CYPRESS_DOWNLOAD_MIRROR，则使用其值代替https://download.cypress.io（注意/desktop保留！）
${platform}替换为运行安装的平台（例如win32、linux、darwin）
${arch}替换为运行安装的架构（例如x64、arm64）
从Cypress 10.6.0开始，${version}替换为正在安装的版本号（例如10.11.0）

示例：

要从与https://cdn.cypress.io完全相同的文件结构的下载镜像安装二进制文件（适用于Cypress 9.3.0或更高版本）：

export CYPRESS_DOWNLOAD_MIRROR=https://cypress-download.local
export CYPRESS_DOWNLOAD_PATH_TEMPLATE='${endpoint}/${platform}-${arch}/cypress.zip'
# 示例结果URL: https://cypress-download.local/desktop/10.11.0/linux-x64/cypress.zip

要从具有自定义文件结构的下载服务器安装二进制文件（适用于Cypress 10.6.0或更高版本）：

export CYPRESS_DOWNLOAD_PATH_TEMPLATE='https://software.local/cypress/${platform}/${arch}/${version}/cypress.zip'
# 示例结果URL: https://software.local/cypress/linux/x64/10.11.0/cypress.zip

要在.npmrc中定义CYPRESS_DOWNLOAD_PATH_TEMPLATE，请在每个$前加上反斜杠（适用于Cypress 9.5.3或更高版本）：

CYPRESS_DOWNLOAD_PATH_TEMPLATE=\${endpoint}/\${platform}-\${arch}/cypress.zip

使用自定义证书颁发机构(CA)

Cypress可以配置为使用npm配置文件中的ca和cafile选项来下载Cypress二进制文件。

例如，要在下载Cypress时使用位于/home/person/certs/ca.crt的CA，请将以下内容添加到你的.npmrc：

cafile=/home/person/certs/ca.crt

如果既未设置cafile也未设置ca，Cypress会查看系统环境变量NODE_EXTRA_CA_CERTS，并在下载Cypress二进制文件时使用相应的证书作为受信任证书颁发机构的扩展。

请注意，npm配置用作替换，而node环境变量用作扩展。

选择不向Cypress发送异常数据

当抛出与Cypress相关的异常时，我们会将异常数据发送到https://api.cypress.io。我们仅使用此信息来帮助开发更好的产品。

如果你想选择不向Cypress发送任何异常数据，可以通过在系统环境变量中设置CYPRESS_CRASH_REPORTS=0来实现。

在Linux或macOS上选择退出

要在Linux或macOS上选择不发送异常数据，请在安装Cypress之前在终端中运行以下命令：

export CYPRESS_CRASH_REPORTS=0

要使这些更改永久生效，可以将此命令添加到shell的~/.profile（~/.zsh_profile、~/.bash_profile等）中，以便在每次登录时运行。

在Windows上选择退出

要在Windows上选择不发送异常数据，请在安装Cypress之前在命令提示符中运行以下命令：

set CYPRESS_CRASH_REPORTS=0

要在PowerShell中实现相同的目的：

$env:CYPRESS_CRASH_REPORTS = "0"

要保存CYPRESS_CRASH_REPORTS变量以供所有新shell使用，请使用setx：

setx CYPRESS_CRASH_REPORTS 0

选择退出Cypress商业消息

Cypress可能会偶尔在你的CI日志中显示与我们商业产品相关的消息，以及它们如何在工作流程中为你带来好处。

如果你想选择退出所有商业消息，可以通过在系统环境变量中设置CYPRESS_COMMERCIAL_RECOMMENDATIONS=0来实现。

安装预发布版本

如果你想安装Cypress的预发布版本以测试尚未发布的功能，方法如下：

打开Cypress仓库的develop分支提交列表： https://github.com/cypress-io/cypress/commits/develop
找到你想安装预发布版本的提交。点击评论图标（下方红色高亮部分）：
你应该会看到来自cypress-bot用户的多条评论，其中包含安装Cypress预发布版本的说明。选择与你的操作系统和CPU架构相对应的那条，并按照那里的说明安装预发布版本。

Cypress预发布版本仅在构建后的60天内可用。不要依赖这些版本在60天后仍然可用。

Windows子系统Linux

Cypress需要X-server(X11)来从Windows子系统Linux安装中显示Cypress UI。当前版本的Windows子系统Linux(WSL2)通过Windows子系统Linux GUI(WSLg)包含X11支持来满足此要求。

参考GitHub: Windows Subsystem for Linux GUI (WSLg)获取在Ubuntu上的安装说明，并在运行Cypress之前安装先决Linux软件包。

参考Microsoft LearnWindows Subsystem for Linux Documentation获取更多信息。

info

Cypress.io并不专门支持在Windows子系统Linux(WSL)下使用Cypress。如果你想报告问题，请确保你可以在不使用WSL的情况下在Cypress支持的操作系统上重现该问题。

卸载Cypress

要从项目中卸载Cypress，请使用与安装Cypress相同的包管理器：

npm
Yarn
pnpm

npm uninstall cypress

yarn remove cypress

pnpm remove cypress

要卸载所有缓存的Cypress二进制版本，请使用cypress cache clear命令，并按照如何运行命令中描述的适当包管理器前缀。或者，手动删除Cypress二进制缓存（见上文）。

要删除缓存的Cypress应用数据，请手动删除以下目录/文件夹：

macOS: ~/Library/Application Support/Cypress
Linux: ~/.config/Cypress
Windows: $APPDATA/Cypress (POSIX语法) 或 %APPDATA%\Cypress (Windows语法)

参考你的包管理器文档以了解包管理器cache clean命令的详细信息，以删除npm、Yarn或pnpm缓存的其他包。

高级安装

你将学到​

环境变量​

安装二进制文件​

跳过安装​

安装问题排查​

二进制缓存​

运行二进制文件​

Mac​

Linux​

Windows​

下载URL​

镜像​

下载路径模板​

使用自定义证书颁发机构(CA)​

选择不向Cypress发送异常数据​

在Linux或macOS上选择退出​

在Windows上选择退出​

选择退出Cypress商业消息​

安装预发布版本​

Windows子系统Linux​

卸载Cypress​

目录