Skip to main content

配置

🌐 Configuration

有头模式和无头模式​

🌐 Headed and headless mode

CLI 默认以无头模式运行。要查看浏览器：

🌐 The CLI runs headless by default. To see the browser:

playwright-cli open https://playwright.nodejs.cn --headed

浏览器选择​

🌐 Browser selection

playwright-cli open --browser=chrome     # Google Chrome (default)
playwright-cli open --browser=firefox    # Mozilla Firefox
playwright-cli open --browser=webkit     # WebKit (Safari engine)
playwright-cli open --browser=msedge     # Microsoft Edge

设备模拟​

🌐 Device emulation

# Emulate a generic mobile device: Pixel 10 for Chromium, iPhone 17 for WebKit
playwright-cli open --mobile

# Emulate a named device from the Playwright device registry
playwright-cli open --device="iPhone 15"

--mobile 默认情况下值得使用，当移动端布局可接受时：移动页面通常更轻量，所以它们的快照更小，成本也更低。

配置文件模式​

🌐 Profile modes

内存中（默认）​

🌐 In-memory (default)

Cookie 和存储在命令之间会持续存在，但在浏览器关闭时会丢失：

🌐 Cookies and storage persist between commands but are lost when the browser closes:

playwright-cli open https://example.com

持久的​

🌐 Persistent

配置文件已保存到磁盘，可在浏览器重启后保留：

🌐 Profile saved to disk, survives browser restarts:

playwright-cli open https://example.com --persistent

自定义配置文件目录​

🌐 Custom profile directory

playwright-cli open https://example.com --profile=./my-profile

孤立的​

🌐 Isolated

显式内存模式 —— 等同于默认模式，但可以在配置文件中设置：

🌐 Explicit in-memory mode — equivalent to the default but can be set in the config file:

{
  "browser": { "isolated": true }
}

配置文件​

🌐 Configuration file

要进行高级设置，请使用配置文件：

🌐 For advanced settings, use a config file:

playwright-cli open example.com --config=path/to/config.json

配置是从四个来源合并的，每个都会覆盖前一个：

🌐 Configuration is merged from four sources, each overriding the previous one:

  1. ~/.playwright/cli.config.json — 每个工作区的全局默认设置
  2. 工作区中的 .playwright/cli.config.json — 当存在时会自动加载，可通过显式 --config 覆盖
  3. PLAYWRIGHT_MCP_* 环境变量
  4. 命令行选项，比如 --browser、--headed、--device、--profile

完整配置架构​

🌐 Full config schema

{
  browser?: {
    browserName?: 'chromium' | 'firefox' | 'webkit';
    isolated?: boolean;            // keep the profile in memory
    userDataDir?: string;
    launchOptions?: {
      channel?: string;            // 'chrome', 'msedge', ...
      headless?: boolean;
      executablePath?: string;
      args?: string[];
      chromiumSandbox?: boolean;
      slowMo?: number;
      timeout?: number;
      proxy?: {
        server: string;            // e.g., "http://myproxy:3128"
        bypass?: string;           // e.g., ".com,chromium.org"
        username?: string;
        password?: string;
      };
    };
    contextOptions?: {
      viewport?: { width: number; height: number };
      locale?: string;
      timezoneId?: string;
      userAgent?: string;
      colorScheme?: 'light' | 'dark' | 'no-preference';
      storageState?: string;
      permissions?: string[];      // e.g., ['geolocation', 'clipboard-read']
      ignoreHTTPSErrors?: boolean;
      serviceWorkers?: 'allow' | 'block';
    };
    cdpEndpoint?: string;
    cdpHeaders?: Record<string, string>;
    cdpTimeout?: number;           // defaults to 30000, 0 disables
    remoteEndpoint?: string | { endpoint: string, headers?, slowMo?, timeout? };
    initPage?: string[];           // TypeScript files for page setup
    initScript?: string[];         // JavaScript files for page init
  };
  extension?: boolean;
  server?: {
    port?: number;
    host?: string;
    allowedHosts?: string[];
  };
  capabilities?: string[];         // MCP tool capabilities; the CLI enables all of them
  saveSession?: boolean;
  sharedBrowserContext?: boolean;
  outputDir?: string;
  outputMaxSize?: number;          // eviction threshold for output files, in bytes
  console?: { level?: 'error' | 'warning' | 'info' | 'debug' };
  network?: {
    allowedOrigins?: string[];     // e.g., ["https://api.example.com", "http://localhost:*"]
    blockedOrigins?: string[];
  };
  secrets?: Record<string, string>;
  testIdAttribute?: string;        // default: "data-testid"
  timeouts?: {
    action?: number;               // default: 5000ms
    navigation?: number;           // default: 60000ms
    expect?: number;               // default: 5000ms
    settle?: number;               // default: 500ms
  };
  imageResponses?: 'allow' | 'omit';
  snapshot?: {
    mode?: 'full' | 'none';
    boxes?: boolean;               // include [box=x,y,width,height] in snapshots
  };
  allowUnrestrictedFileAccess?: boolean;
  codegen?: 'typescript' | 'python' | 'java' | 'csharp' | 'none';
}

示例配置​

🌐 Example configs

本地开发：

{
  "browser": {
    "launchOptions": { "headless": false }
  }
}

CI 环境：

{
  "browser": {
    "launchOptions": { "headless": true },
    "contextOptions": { "viewport": { "width": 1280, "height": 720 } }
  },
  "outputDir": "./test-output"
}

在代理服务器后面：

{
  "browser": {
    "launchOptions": {
      "proxy": {
        "server": "http://proxy.corp.example.com:8080",
        "bypass": "localhost,*.internal.com"
      }
    }
  }
}

设备模拟：

{
  "browser": {
    "contextOptions": {
      "viewport": { "width": 375, "height": 812 },
      "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X)..."
    }
  }
}

初始化脚本：

{
  "browser": {
    "initScript": ["./setup.js"],
    "initPage": ["./setup-page.ts"]
  }
}

打印已解析的配置​

🌐 Print resolved config

查看合并了 CLI 选项、环境变量和配置文件后的最终配置：

🌐 See the final config after merging CLI options, environment variables, and config files:

playwright-cli config-print

浏览器扩展​

🌐 Browser extension

连接到你现有的浏览器标签页，而不是启动新的浏览器：

🌐 Connect to your existing browser tabs instead of launching a new browser:

playwright-cli attach --extension

详情请参见 Attach。

🌐 See Attach for details.

环境变量​

🌐 Environment variables

变量描述
PLAYWRIGHT_CLI_SESSION默认会话名称
PLAYWRIGHT_MCP_ALLOWED_HOSTS服务器允许的主机（用逗号分隔）
PLAYWRIGHT_MCP_ALLOWED_ORIGINS浏览器可能请求的来源（以分号分隔）
PLAYWRIGHT_MCP_ALLOW_UNRESTRICTED_FILE_ACCESS允许访问工作区外的文件
PLAYWRIGHT_MCP_BLOCKED_ORIGINS源头到阻止（用分号分隔）
PLAYWRIGHT_MCP_BLOCK_SERVICE_WORKERS阻止服务工作者
PLAYWRIGHT_MCP_BROWSER使用的浏览器（chrome、firefox、webkit、msedge 等）
PLAYWRIGHT_MCP_CAPS启用功能（逗号分隔）
PLAYWRIGHT_MCP_CDP_ENDPOINTCDP 端点
PLAYWRIGHT_MCP_CDP_HEADERS发送 CDP 连接请求时的请求头
PLAYWRIGHT_MCP_CDP_TIMEOUTCDP 连接超时 (毫秒)
PLAYWRIGHT_MCP_CODEGEN代码生成语言
PLAYWRIGHT_MCP_CONFIG配置文件路径
PLAYWRIGHT_MCP_CONSOLE_LEVEL控制台消息级别
PLAYWRIGHT_MCP_DEVICE模拟设备
PLAYWRIGHT_MCP_EXECUTABLE_PATH自定义浏览器可执行文件
PLAYWRIGHT_MCP_EXTENSION通过浏览器扩展连接
PLAYWRIGHT_MCP_GRANT_PERMISSIONS浏览器权限（逗号分隔）
PLAYWRIGHT_MCP_HEADLESS无头运行
PLAYWRIGHT_MCP_HOST绑定服务器的主机
PLAYWRIGHT_MCP_IGNORE_HTTPS_ERRORS忽略 HTTPS 错误
PLAYWRIGHT_MCP_IMAGE_RESPONSESallow 或 omit
PLAYWRIGHT_MCP_INIT_PAGE页面初始化 TypeScript
PLAYWRIGHT_MCP_INIT_SCRIPT页面初始化 JavaScript
PLAYWRIGHT_MCP_ISOLATED内存中的配置文件
PLAYWRIGHT_MCP_MOBILE模拟一个通用的移动设备
PLAYWRIGHT_MCP_OUTPUT_DIR输出目录
PLAYWRIGHT_MCP_OUTPUT_MAX_SIZE输出逐出阈值（字节）
PLAYWRIGHT_MCP_PORT服务器端口
PLAYWRIGHT_MCP_PROFILE_DIR_NAME扩展模式的配置文件目录名
PLAYWRIGHT_MCP_PROXY_BYPASS绕过代理的域名
PLAYWRIGHT_MCP_PROXY_SERVER代理服务器 URL
PLAYWRIGHT_MCP_REMOTE_HEADERS远程端点连接请求的头信息
PLAYWRIGHT_MCP_SANDBOX启用或禁用 Chromium 沙箱
PLAYWRIGHT_MCP_SECRETS_FILE秘密文件（dotenv）
PLAYWRIGHT_MCP_STORAGE_STATE存储状态文件
PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE测试 ID 属性
PLAYWRIGHT_MCP_TIMEOUT_ACTION动作超时（毫秒）
PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION导航超时（毫秒）
PLAYWRIGHT_MCP_TIMEOUT_SETTLE操作后结算超时（毫秒）
PLAYWRIGHT_MCP_USER_AGENT自定义用户代理
PLAYWRIGHT_MCP_USER_DATA_DIR配置文件目录
PLAYWRIGHT_MCP_VIEWPORT_SIZE视口大小（例如，“1280x720”）

所有打开和附加参数​

🌐 All open and attach parameters

playwright-cli open [url]                          # open browser
playwright-cli open --headed                       # show browser window
playwright-cli open --browser=firefox              # specific browser
playwright-cli open --mobile                       # generic mobile device
playwright-cli open --device="iPhone 15"           # named device
playwright-cli open --persistent                   # persist profile to disk
playwright-cli open --profile=<path>               # custom profile directory
playwright-cli open --config=file.json             # use config file

playwright-cli attach [name]                       # attach to a bound browser by name
playwright-cli attach --extension                  # connect via extension
playwright-cli attach --cdp=chrome                 # connect to a running channel
playwright-cli attach --cdp=<url>                  # connect via CDP endpoint
playwright-cli attach --endpoint=<url>             # connect to a Playwright server
playwright-cli attach --config=file.json           # use config file