camoufox-2026

用途

Camoufox 2026 用于反检测（anti-detect）的隐蔽浏览器自动化。凡是必须规避自动化识别、又需要真实浏览器行为的场景，都可以使用该技能。它与原生 Playwright 最主要的区别在于：标准 Playwright 会泄漏自动化特征，例如 navigator.webdriver = true、注入到页面作用域的 window.playwright__binding，以及 CDP（Chrome DevTools Protocol）指纹信号。Camoufox 在 C++ 层面修补 Firefox（通过 Juggler 协议，即 Firefox 对应 CDP 的机制），使 Playwright 的动作运行在页面之外的隔离作用域中，网站无法看到这些动作。同时通过 BrowserForge 进行指纹轮换，模拟真实世界设备分布。

2026 状态提示

截至 v146.0.1-beta.25（2026 年 1 月），Camoufox 源码公开但高度实验性：最新版不适合生产环境，可能引入破坏性变更；由于 Firefox 基础版本差距和新的指纹不一致问题，性能较此前版本有所下降；开发在经历一段维护空窗后于 2025 年末/2026 年初恢复。若要稳定用于生产，应锁定最后已知良好版本，升级前先测试。

主要能力

反检测：修补 navigator.webdriver、Playwright 注入绑定、CDP 指纹信号等泄漏点，动作在页面外隔离作用域执行。
指纹轮换：BrowserForge 生成统计上真实的设备画像，包括 Navigator 属性（操作系统、硬件、屏幕）、WebGL renderer 与 vendor、AudioContext 指纹、字体和 locale，并遵循真实世界操作系统市场份额分布（如 Linux 约 5%、Windows 约 70% 等）。每个新的浏览器实例自动获得全新指纹。
拟人化（humanize=True）：启用距离感知的曲线鼠标轨迹（C++ HumanCursor 算法）、随机打字节奏、自然滚动模式、动作微延迟。但并非完美，复杂的行为分析仍可能检测到；可额外补充随机动作时序、避免突发交互、不要重复相同的交互序列。
持久化会话（persistent_context）：对需要在容器重启后存活的登录会话很关键；路径必须是目录，Camoufox 会在其中保存 cookies、localStorage 和 IndexedDB。
GeoIP 匹配：geoip=True 可根据代理 IP 自动推导 locale 与时区，也可配置代理。

安装方式

2026 年新项目应使用 uv（而非 pip）：

# Always use uv (not pip) for new projects in 2026
uv add camoufox[geoip]
uv add playwright

# Download Camoufox's patched Firefox binary (one-time, ~300MB)
# ⚠️  This fetches a pre-built binary from GitHub releases.
#    Pin the camoufox version in pyproject.toml and verify the
#    download hash before deploying to production.
python -m camoufox fetch

注意：camoufox fetch 会下载第三方修补版 Firefox 二进制。应在 pyproject.toml / uv.lock 中锁定 camoufox 包版本，并在生产或 CI 使用前通过 GitHub release 校验和验证来源。

使用方式

异步模式（推荐，配合 FastAPI 使用）：

import asyncio
from camoufox.async_api import AsyncCamoufox

async def main():
    async with AsyncCamoufox(
        headless=False,           # False = uses virtual display (Xvfb)
        humanize=True,            # enables human-like mouse/timing
        persistent_context="/sessions/my-app",  # saves cookies/storage
        geoip=True,               # auto locale/timezone from IP
    ) as browser:
        page = await browser.new_page()
        await page.goto("https://www.example.com")
        # actions...

asyncio.run(main())

同步模式（仅用于简单脚本）：

from camoufox.sync_api import Camoufox

with Camoufox(
    headless=False,
    humanize=True,
    persistent_context="/sessions/my-app",
) as browser:
    page = browser.new_page()
    page.goto("https://www.example.com")

持久化上下文（会话存活）：

async with AsyncCamoufox(
    persistent_context="/sessions/my-app",  # mount as Docker volume
    headless=False,
) as browser:
    page = await browser.new_page()
    await page.goto("https://www.example.com")
    # First run: login manually via VNC
    # Subsequent runs: session restored automatically

Docker 卷挂载：

volumes:
  - ./sessions:/sessions  # restrict permissions: chown to container UID, chmod 700

重要：会话目录包含认证令牌和 cookies，应限制宿主机权限（chmod 700 ./sessions），切勿将会话数据提交到版本控制。

代理与 GeoIP：

import os

async with AsyncCamoufox(
    geoip=True,           # auto-derive locale/timezone from proxy IP
    proxy={
        "server": os.environ["PROXY_URL"],       # e.g. http://proxy-ip:port
        "username": os.environ["PROXY_USER"],
        "password": os.environ["PROXY_PASS"],    # never hardcode credentials
    }
) as browser:
    ...

切勿在源码中硬编码代理凭据，应从环境变量或密钥管理器加载。

VPS 上的无头模式（需要 Xvfb）：Camoufox 即使在“无头”模式下也需要显示环境才能实现完整隐蔽性。应设置 headless=False 并在外部运行 Xvfb。

import os
os.environ["DISPLAY"] = ":99"  # match your Xvfb display number

async with AsyncCamoufox(headless=False, ...) as browser:
    ...

适用场景

任何必须规避自动化检测的浏览器自动化任务。
需要登录会话跨容器重启存活的自动化流程。
需要配合代理并让 locale/时区与 IP 一致的任务。

限制与未覆盖范围

Cloudflare 中间页 WAF：会检测 SpiderMonkey 引擎行为，无法完全伪装。
复杂的 ML 行为分析：鼠标模式仍可能被标记。
非 Python 语言：需使用远程服务器模式（见官方文档）。

反模式（禁止做法）

# ❌ DO NOT use raw Playwright for stealth work
from playwright.async_api import async_playwright  # will get detected

# ❌ DO NOT use sync in async FastAPI context
from camoufox.sync_api import Camoufox  # blocks event loop

# ❌ DO NOT use time.sleep() — use asyncio.sleep()
import time; time.sleep(2)  # breaks async event loop

# ❌ DO NOT install via pip in 2026 new projects
pip install camoufox  # use uv instead

正确模式：使用异步加随机延迟 await asyncio.sleep(random.uniform(0.8, 3.0))；使用 locators 而非脆弱的 CSS/XPath 字符串；导航后等待网络空闲 await page.goto(url, wait_until="networkidle")；用截图辅助调试（保存到 /sessions/）。

安全与供应链提示

Camoufox 分发的是修补版 Firefox 二进制，属于第三方供应链依赖。采用前应：在 GitHub releases 页面验证发布签名/校验和、锁定包版本、升级前审计更新。

参考资料

官方文档：https://camoufox.com GitHub：https://github.com/daijro/camoufox 隐蔽机制细节：https://camoufox.com/stealth/