配置

🌐 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

playwright-cli open --device="iPhone 15" https://example.com

视口大小

🌐 Viewport size

playwright-cli open --viewport-size=1280x720 https://example.com

代理

🌐 Proxy

playwright-cli open --proxy-server=http://myproxy:3128 --proxy-bypass=localhost,*.internal.com https://example.com

配置文件模式

🌐 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

对于高级设置，请使用 JSON 配置文件：

🌐 For advanced settings, use a JSON config file:

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

如果存在，CLI 会自动加载 .playwright/cli.config.json。

🌐 The CLI automatically loads .playwright/cli.config.json if present.

完整配置架构

🌐 Full config schema

{
  browser?: {
    browserName?: 'chromium' | 'firefox' | 'webkit';
    isolated?: boolean;
    userDataDir?: string;
    launchOptions?: {
      channel?: string;           // 'chrome', 'msedge'
      headless?: boolean;
      executablePath?: string;
      args?: string[];
      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;
      userAgent?: string;
      storageState?: string;
      permissions?: string[];     // e.g., ['geolocation', 'clipboard-read']
      serviceWorkers?: 'allow' | 'block';
    };
    cdpEndpoint?: string;
    cdpHeaders?: Record<string, string>;
    cdpTimeout?: number;
    remoteEndpoint?: string;
    initPage?: string[];          // TypeScript files for page setup
    initScript?: string[];        // JavaScript files for page init
  };
  extension?: boolean;
  saveVideo?: { width: number; height: number };
  saveSession?: boolean;
  sharedBrowserContext?: boolean;
  snapshot?: { mode?: 'full' | 'none' };
  imageResponses?: 'allow' | 'omit';
  outputDir?: string;
  outputMode?: 'file' | 'stdout';
  console?: { level?: 'error' | 'warning' | 'info' | 'debug' };
  network?: {
    allowedOrigins?: string[];    // e.g., ["https://api.example.com"]
    blockedOrigins?: string[];    // e.g., ["https://analytics.example.com"]
  };
  secrets?: Record<string, string>;
  testIdAttribute?: string;       // default: "data-testid"
  timeouts?: {
    action?: number;              // default: 5000ms
    navigation?: number;          // default: 60000ms
    expect?: number;              // default: 5000ms
  };
  allowUnrestrictedFileAccess?: boolean;
  codegen?: 'typescript' | '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

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

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

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_BROWSER`	使用的浏览器（chrome、firefox、webkit、msedge）
`PLAYWRIGHT_MCP_HEADLESS`	无头运行
`PLAYWRIGHT_MCP_CAPS`	启用功能（逗号分隔）
`PLAYWRIGHT_MCP_CONFIG`	配置文件路径
`PLAYWRIGHT_MCP_ISOLATED`	内存中的配置文件
`PLAYWRIGHT_MCP_EXTENSION`	通过浏览器扩展连接
`PLAYWRIGHT_MCP_USER_DATA_DIR`	配置文件目录
`PLAYWRIGHT_MCP_STORAGE_STATE`	存储状态文件
`PLAYWRIGHT_MCP_DEVICE`	模拟设备
`PLAYWRIGHT_MCP_EXECUTABLE_PATH`	自定义浏览器可执行文件
`PLAYWRIGHT_MCP_VIEWPORT_SIZE`	视口大小（例如，“1280x720”）
`PLAYWRIGHT_MCP_PROXY_SERVER`	代理服务器 URL
`PLAYWRIGHT_MCP_PROXY_BYPASS`	绕过代理的域名
`PLAYWRIGHT_MCP_USER_AGENT`	自定义用户代理
`PLAYWRIGHT_MCP_IGNORE_HTTPS_ERRORS`	忽略 HTTPS 错误
`PLAYWRIGHT_MCP_TIMEOUT_ACTION`	动作超时（毫秒）
`PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION`	导航超时（毫秒）
`PLAYWRIGHT_MCP_CONSOLE_LEVEL`	控制台消息级别
`PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE`	测试 ID 属性
`PLAYWRIGHT_MCP_CDP_ENDPOINT`	CDP 端点
`PLAYWRIGHT_MCP_OUTPUT_DIR`	输出目录
`PLAYWRIGHT_MCP_CODEGEN`	代码生成语言
`PLAYWRIGHT_MCP_INIT_PAGE`	页面初始化 TypeScript
`PLAYWRIGHT_MCP_INIT_SCRIPT`	页面初始化 JavaScript
`PLAYWRIGHT_MCP_BLOCKED_ORIGINS`	阻止来源
`PLAYWRIGHT_MCP_ALLOWED_ORIGINS`	允许来源
`PLAYWRIGHT_MCP_GRANT_PERMISSIONS`	浏览器权限
`PLAYWRIGHT_MCP_BLOCK_SERVICE_WORKERS`	阻止服务工作者
`PLAYWRIGHT_MCP_NO_SANDBOX`	禁用沙箱
`PLAYWRIGHT_MCP_SAVE_SESSION`	保存会话数据
`PLAYWRIGHT_MCP_SAVE_VIDEO`	自动录制视频（例如，“800x600”）
`PLAYWRIGHT_MCP_SECRETS_FILE`	秘密文件（dotenv）

所有未确定的参数

🌐 All open parameters

playwright-cli open [url]                          # open browser
playwright-cli open --headed                       # show browser window
playwright-cli open --browser=firefox              # specific browser
playwright-cli open --device="iPhone 15"           # device emulation
playwright-cli open --viewport-size=1280x720       # viewport size
playwright-cli open --persistent                   # persist profile to disk
playwright-cli open --profile=<path>               # custom profile directory
playwright-cli open --proxy-server=<url>           # proxy server
playwright-cli open --proxy-bypass=<hosts>         # bypass proxy
playwright-cli open --user-agent=<ua>              # custom user agent
playwright-cli open --ignore-https-errors          # ignore HTTPS errors
playwright-cli open --config=file.json             # use config file
playwright-cli attach --extension                  # connect via extension
playwright-cli attach --cdp <url>                  # connect via CDP
playwright-cli attach --endpoint <url>             # connect to Playwright server

有头模式和无头模式​

浏览器选择​

设备模拟​

视口大小​

代理​

配置文件模式​

内存中（默认）​

持久的​

自定义配置文件目录​

孤立的​

配置文件​

完整配置架构​

示例配置​

打印已解析的配置​

浏览器扩展​

环境变量​

所有未确定的参数​