Windows 下能否将 ms-playwright 安装到 %USERPROFILE% 以外？

2026-11-04技术老齐

结论

可以。Playwright 提供了 PLAYWRIGHT_BROWSERS_PATH 环境变量，用来指定浏览器二进制文件的下载和查找目录。在 Windows 中，可以将它设置为 C:\targetDirectory\ms-playwright 这样的绝对路径。安装浏览器和运行测试时使用相同的设置，就不会再把 Playwright 浏览器安装到 %USERPROFILE%\AppData\Local\ms-playwright。

不要修改 USERPROFILE。它表示 Windows 用户主目录，会影响 Firefox、Node.js 和其他程序。题目中的“relative home directory”错误检查的是用户主目录，与 Playwright 浏览器的安装目录无关。

PowerShell 配置方式

以下设置仅对当前 PowerShell 会话生效：

$env:PLAYWRIGHT_BROWSERS_PATH = "C:\targetDirectory\ms-playwright"

npm install
npx playwright install
npx playwright test

也可以明确安装三种 Playwright 浏览器：

$env:PLAYWRIGHT_BROWSERS_PATH = "C:\targetDirectory\ms-playwright"

npx playwright install chromium firefox webkit
npx playwright test

如果使用 Playwright for .NET，请先设置变量，再执行生成的安装脚本：

$env:PLAYWRIGHT_BROWSERS_PATH = "C:\targetDirectory\ms-playwright"

pwsh .\bin\Debug\net8.0\playwright.ps1 install
dotnet test

其中 net8.0 要替换成项目实际使用的目标框架目录。

如果需要让该变量对当前用户以后启动的进程长期生效，可以运行：

[Environment]::SetEnvironmentVariable(
    "PLAYWRIGHT_BROWSERS_PATH",
    "C:\targetDirectory\ms-playwright",
    "User"
)

设置完成后，需要重新打开终端或重启 IDE，让新进程读取该变量。

CMD 配置方式

以下设置仅对当前命令提示符会话生效：

set PLAYWRIGHT_BROWSERS_PATH=C:\targetDirectory\ms-playwright
npm install
npx playwright install chromium firefox webkit
npx playwright test

要将变量长期保存到当前用户环境中，可以运行：

setx PLAYWRIGHT_BROWSERS_PATH "C:\targetDirectory\ms-playwright"

setx 不会修改当前窗口中的环境变量，保存后需要打开新的终端。

安装和运行时必须使用同一路径

PLAYWRIGHT_BROWSERS_PATH 既决定浏览器的安装位置，也决定 Playwright 运行时从哪里查找浏览器。如果只在安装时设置变量，运行测试时没有设置，Playwright 仍可能回到默认目录查找，并报告浏览器不存在。

CI、IDE、测试运行器和普通终端都应使用相同的配置。例如，可以在 PowerShell 脚本中统一设置：

$env:PLAYWRIGHT_BROWSERS_PATH = "C:\targetDirectory\ms-playwright"

npx playwright install chromium firefox webkit

if ($LASTEXITCODE -ne 0) {
    exit $LASTEXITCODE
}

npx playwright test

目标目录必须使用绝对路径，当前用户还需要拥有读取、写入和执行权限。

将浏览器放在项目自身目录

Playwright 也支持“hermetic install”模式：

$env:PLAYWRIGHT_BROWSERS_PATH = "0"
npx playwright install

这种模式会把浏览器放入 Playwright 包附近的 .local-browsers 目录。如果项目及其依赖位于 C:\targetDirectory 下，浏览器通常也会位于这个目录树中。

如果企业安全策略要求使用固定且便于审计的目录，直接指定绝对路径会更清楚：

C:\targetDirectory\ms-playwright

不要通过修改 USERPROFILE 来搬迁浏览器

不要使用下面这种设置：

$env:USERPROFILE = ".\somewhere"

USERPROFILE 是 Windows 用户主目录，不是 Playwright 的专用配置。Firefox 启动代码要求 os.homedir() 返回绝对路径。如果将它改成相对路径，就会触发类似下面的错误：

Cannot launch Firefox with relative home directory.

即使将 USERPROFILE 改成另一个绝对路径，也可能影响 npm、浏览器配置、证书、缓存和其他工具。迁移 Playwright 浏览器时，应设置 PLAYWRIGHT_BROWSERS_PATH，同时保留正常的绝对 USERPROFILE。

Playwright 所说的 browsers 是什么

Playwright 默认安装与当前 Playwright 版本匹配的浏览器构建，包括：

Chromium
Playwright 定制或匹配的 Firefox
WebKit

其中的 Chromium 并不是 Windows 中安装的品牌版 Google Chrome。Playwright 可以通过 channel: "chrome" 使用系统安装的 Chrome，例如：

import { chromium } from '@playwright/test';

const browser = await chromium.launch({
  channel: 'chrome',
});

也可以通过 executablePath 指向指定的程序：

const browser = await chromium.launch({
  executablePath: 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
});

使用 executablePath 指向任意浏览器版本时，Playwright 不保证所有功能都能兼容。Firefox 和 WebKit 对 Playwright 配套浏览器构建的依赖尤其明显，不能直接用系统 Firefox 或其他浏览器完全替代。如果需要稳定运行 Chromium、Firefox 和 WebKit 测试，仍应通过 playwright install 安装配套版本。

如果只使用系统浏览器，可以在安装依赖时设置：

$env:PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD = "1"
npm install

然后在测试配置中选择 channel 或 executablePath。这个变量只会阻止浏览器下载，不会自动配置系统浏览器的位置。

“全部安装到目标目录”仍有边界

PLAYWRIGHT_BROWSERS_PATH 可以迁移 ms-playwright 中的浏览器、相关 executable，以及随浏览器分发的 DLL。Playwright 库本身仍会安装在项目依赖目录中，例如：

C:\targetDirectory\applications\targetApplication\node_modules

运行期间还可能使用以下位置：

Windows 临时目录；
浏览器临时用户数据目录；
测试输出、截图、视频和 trace 目录；
npm、NuGet 或其他包管理器的缓存目录；
系统浏览器自身的安装目录和用户数据目录。

设置 PLAYWRIGHT_BROWSERS_PATH 可以解决默认 ms-playwright 目录的问题，但不能保证进程不会访问 C:\targetDirectory 以外的文件。如果安全策略要求所有 executable、DLL、临时文件和缓存都必须位于豁免目录，还需要根据公司的执行控制日志检查实际访问路径，并按需配置 TEMP、TMP、测试输出目录和包管理器缓存。最终是否满足 IT Security 要求，应由负责该策略的团队确认。