跳到主要内容
如何使用 Capium Browser

安装、认证,然后开始驱动。

Capium Browser 是我们自研的隐身 Chrome,按会话授权,一条命令即可安装。填入许可证密钥,即可用你熟悉的 Playwright API 在本地驱动它。

像使用 Playwright 一样驱动它

导航、点击、输入、等待选择器和网络请求。原生 Playwright API 无需任何改动即可使用。

真正的隐身 Chrome

货真价实、始终保持最新版本的 Chrome 内核,针对机器人检测进行了加固,而不是无头桩程序或打过补丁的封装。

截图与 PDF

截取整页截图,或将任意页面渲染为 PDF,与使用本地浏览器完全一样。

并发会话

可同时运行多个浏览器。每个运行中的浏览器计为一个会话,占用你套餐的上限。

1. 快速开始

为你的语言安装工具包。无需自行部署,也无需打补丁。隐身二进制文件会在首次运行时获取,并自动保持更新。

install.sh
# Python
pip install capiumbrowser
python -m playwright install-deps   # Chromium's OS libraries (once)

# JavaScript / TypeScript
npm install capiumbrowser

填入许可证密钥,驱动你的第一个页面。开启 humanize=True 可获得拟人化的输入与节奏。

first_run.py
from capiumbrowser import launch_context

# Your license key is on the dashboard: Dashboard -> Capium Browser.
# Export it once:  export CAPIUM_LICENSE_KEY="CAPIUM-XXXX-XXXX-XXXX-XXXX"
# launch_context returns (browser, context, page); the always-latest
# stealth binary is downloaded on first run.
browser, ctx, page = launch_context(
    seed=200123,        # one seed = one coherent device
    humanize=True,      # human-like input + timing
    url="https://example.com",
)
print(page.title())
browser.close()

2. 身份验证

你的许可证密钥位于控制台的 Capium Browser 下。你可以在那里显示、复制或重新签发。请妥善保密,并从环境变量加载,而不是硬编码在代码中。

auth.py
# Keep the key out of source. Export it in your shell or CI:
#   export CAPIUM_LICENSE_KEY="CAPIUM-XXXX-XXXX-XXXX-XXXX"
# The SDK reads it from the environment (or ~/.capium/license)
# automatically — nothing to pass in code.
from capiumbrowser import launch_context

browser, ctx, page = launch_context(seed=200123)
  • 如果密钥泄露,请在控制台重新签发。旧密钥会立即失效。
  • 每个账户一个有效许可证。更高等级可同时运行更多会话。
  • 密钥用于授权二进制文件,无需单独登录或 cookie。

3. 使用 Playwright 驱动(Python)

你在 Playwright 中熟悉的一切都可以使用:定位器、等待、网络拦截等。Capium 只是换上了一个加固过的真实 Chrome 内核。

playwright.py
from capiumbrowser import launch_context

browser, ctx, page = launch_context(seed=200123, humanize=True)

page.goto("https://example.com/login")
page.fill("#email", "[email protected]")
page.fill("#password", "hunter2")
page.click("button[type=submit]")
page.wait_for_url("**/dashboard")

# The Playwright API you already know: locators, waits, network, etc.
print(page.locator("h1").inner_text())
browser.close()

4. 异步 API

异步 API 与同步 API 一一对应:launch_context_async 返回相同的(browser, context, page)三元组,并提供可 await 的 Playwright 方法。

async_run.py
import asyncio
from capiumbrowser import launch_context_async

async def main():
    browser, ctx, page = await launch_context_async(
        seed=200123, humanize=True, url="https://example.com",
    )
    print(await page.title())
    await browser.close()

asyncio.run(main())

5. 拟人化模式

启动时传入 humanize=True 会加入拟人化的输入与节奏:自然的鼠标移动、真实的打字节奏、细微的随机停顿,并提供 page.human_type 和 page.human_scroll 辅助方法。交互式流程建议保持开启;追求速度的纯抓取解析场景可以关闭。

humanize.py
browser, ctx, page = launch_context(seed=200123, humanize=True)

page.human_type("#email", "[email protected]")   # natural typing cadence
page.human_scroll(1200)                          # smooth, variable scrolling

6. 会话与并发

每个运行中的浏览器就是一个会话。套餐的会话上限就是你可以同时运行的数量。用完后关闭浏览器即可释放会话。

concurrent.py
import concurrent.futures
from capiumbrowser import launch_context

def fetch(url, seed):
    browser, ctx, page = launch_context(seed=seed, url=url)
    title = page.title()
    browser.close()
    return title

# Each live browser counts as one session against your plan's cap.
urls = ["https://a.example", "https://b.example", "https://c.example"]
seeds = range(200001, 200001 + len(urls))   # one coherent device per worker
with concurrent.futures.ThreadPoolExecutor(max_workers=3) as pool:
    print(list(pool.map(fetch, urls, seeds)))

7. 使用示例:截图与 PDF

capture.py
page.goto("https://example.com")

# Full-page screenshot
page.screenshot(path="shot.png", full_page=True)

# Render the page to a PDF
page.pdf(path="page.pdf", format="A4")

8. 平台与 CI

提供 Linux、Windows 和 macOS 原生二进制文件,在你的笔记本、CI 运行器和服务器集群上行为完全一致。在 CI 中,请将许可证密钥设置为机密环境变量:

ci.yml
# GitHub Actions / GitLab CI
env:
  CAPIUM_LICENSE_KEY: ${{ secrets.CAPIUM_LICENSE_KEY }}

9. 故障排查

许可证无效或已过期

确认密钥与控制台中的一致,且你的许可证(或试用)仍然有效。如有需要,请重新签发密钥。

已达到会话上限

你运行中的浏览器数量已达到套餐允许的上限。请关闭已完成的浏览器,或升级以获得更高的会话上限。

二进制文件无法下载

二进制文件在首次运行时获取,请允许出站 HTTPS。在受限的 CI 环境中,请在多次运行之间缓存工具包。

10. 常见问题

我的许可证密钥在哪里?›

在控制台的 Capium Browser 下。你可以在那里显示、复制或重新签发密钥。请妥善保密,像对待密码一样对待它。

需要手动下载任何东西吗?›

不需要。工具包会在首次运行时为你的操作系统获取最新的加固版二进制文件,并自动保持更新。

支持哪些语言和驱动?›

Python 是官方首选,使用你已经熟悉的原生 Playwright API 驱动。JavaScript/TypeScript 包可通过 npm 以 capiumbrowser 安装。

什么算作一个会话?›

一个运行中的浏览器实例。套餐的会话上限是你可以同时运行的数量,而不是每月总数。

免费试用会过期吗?›

会。试用期提供 1 个浏览器会话,为期 30 天,到期后结束。随时可以升级以获得更多会话和支持。

准备好开始了吗?

获取许可证密钥,几分钟内即可运行你的第一个隐身会话。

打开控制台