camoufox-2026

Camoufox 2026 — 反检测浏览器自动化

⚠️ 2026 年状态警告

截至 v146.0.1-beta.25（2026 年 1 月），Camoufox 源码已公开，但仍处于高度实验阶段。

• 最新版本不适合用于生产环境——可能会有破坏性变更
• 由于 Firefox 基础版本存在差距，且出现新的指纹不一致问题，性能较之前版本有所下降
• 在经历一段维护空档后，开发工作于 2025 年底／2026 年初恢复
• 如需稳定地用于生产环境，请固定到最后一个已知良好版本，并在升级前进行测试

Camoufox 的作用（与原生 Playwright 对比）

标准 Playwright 会通过以下方式泄露自动化痕迹：

• navigator.webdriver = true
• 将 window.__playwright__binding__ 注入页面作用域
• CDP（Chrome DevTools Protocol）指纹信号

Camoufox 在 C++ 层面修补 Firefox（通过 Juggler 协议——Firefox 对应 CDP 的协议）。 Playwright 操作在页面外的隔离作用域中运行——网站无法看到这些操作。 此外，BrowserForge 会通过轮换指纹来模拟真实世界的设备分布。

安装（2026 年）

# 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 发布校验和 验证来源。

API：两种模式

异步（首选——与 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")

持久化上下文（会话持久化）

对于需要在容器重启后继续使用的登录会话，这一点至关重要。

# Path must be a directory — Camoufox stores cookies + localStorage + IndexedDB there
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

重要

会话目录包含身份验证令牌和 Cookie。 限制主机端权限（chmod 700 ./sessions），绝不要将会话数据 提交到版本控制系统。

Humanize 标志——功能说明

humanize=True 会启用：

• 根据移动距离生成弯曲轨迹的鼠标移动（C++ HumanCursor 算法）
• 随机化的打字节奏
• 自然的滚动模式
• 操作间的微小延迟

⚠️ 并非万无一失——复杂的行为分析仍可检测到这些特征。建议配合以下措施：

• 在自己的代码中随机化操作时间
• 避免连续快速交互（添加 await asyncio.sleep(random.uniform(0.5, 2.5))）
• 不要反复执行完全相同的交互序列

指纹轮换

BrowserForge 会生成符合统计规律的真实设备配置：

• Navigator 属性（操作系统、硬件、屏幕）
• WebGL 渲染器和供应商
• AudioContext 指纹
• 字体和区域设置
• 符合真实世界的操作系统市场分布（Linux 约 5%、Windows 约 70% 等）

每个新的浏览器实例都会自动获得一个全新的指纹。

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:
    ...

注意

绝不要在源代码中硬编码代理凭据。请从 环境变量或密钥管理器（例如 Docker secrets、 从版本控制中排除的 .env 文件）中读取凭据。

VPS 上的无头模式（需要 Xvfb）

即使在“无头”模式下，Camoufox 也需要显示器才能实现完全隐身。 设置 headless=False，并在外部运行 Xvfb（在我们的 Docker 设置中由 entrypoint.sh 处理）。

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

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

Camoufox 无法处理的情况

• Cloudflare Interstitial WAF（会测试 SpiderMonkey 引擎行为——无法完全伪装）
• 复杂的 ML 行为分析（鼠标模式仍可能被标记）
• 非 Python 语言（Node/Go 请使用远程服务模式——参阅官方文档）

反模式（绝不要这样做）

# ❌ 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

正确做法

# ✅ Async + proper delay
import asyncio, random
await asyncio.sleep(random.uniform(0.8, 3.0))

# ✅ Use locators (stable selectors, not fragile CSS/XPath strings)
await page.get_by_role("button", name="Post").click()
await page.get_by_placeholder("What's on your mind").fill("text")

# ✅ Wait for network idle after navigation
await page.goto(url, wait_until="networkidle")

# ✅ Screenshot for debugging (saves to /sessions/)
await page.screenshot(path="/sessions/debug.png")

参考资料

• 官方文档：https://camoufox.com
• GitHub：https://github.com/daijro/camoufox
• 隐身机制内部原理：https://camoufox.com/stealth/

警告

Camoufox 会分发经过修补的 Firefox 二进制文件——这属于第三方供应链依赖。 在采用之前：请在 GitHub 发布页面 验证发布签名／校验和，固定包版本，并在升级前审查更新。