未由用户设置的配置数据将使用 [BrowserForge](https://github.com/daijro/browserforge) 指纹自动填充，这些指纹模拟真实流量中设备特征的统计分布。

[[查看已实现的属性](https://camoufox.com/fingerprint/)]

---

## Python 用法

Camoufox 与您现有的 Playwright 代码兼容。您只需更改浏览器初始化方式。

**同步 API**```python
from camoufox.sync_api import Camoufox

with Camoufox() as browser:
    page = browser.new_page()
    page.goto("https://example.com")

[[安装与使用](https://camoufox.com/python/)]

### 充分利用硬件指纹伪装

对于稳定版本，你应始终使用主 [`camoufox`](https://pypi.org/project/camoufox/) pip 包。不过，如果你想利用按上下文（per-context）指纹和硬件伪装功能，请使用 [`cloverlabs-camoufox`](https://pypi.org/project/cloverlabs-camoufox/) 包。该包随每次发布同步更新，而官方包则延迟发布。

请确保你使用虚拟环境，以避免两个包之间发生冲突。

**安装**```bash
pip install cloverlabs-camoufox

**用法** — 该 API 与上游包完全相同：```python
from camoufox.sync_api import Camoufox

with Camoufox() as browser:
    page = browser.new_page()
    page.goto("https://example.com")

库会根据二进制版本自动路由：Firefox ≥ 149 加载 `fingerprint-presets-v150.json`（312 个预设，覆盖 v149–v152，67 个 macOS / 180 个 Windows / 65 个 Linux）；旧版二进制文件回退到原始捆绑包。UA 字符串会被重写以匹配当前激活的二进制版本，因此跨版本启用是安全的。传入预设字典而不是 `True` 可固定特定的指纹。

---

## 功能特性

以下是 Camoufox 中实现的补丁和功能列表。

### 指纹伪装

- 伪装 Navigator 属性（设备、浏览器、区域设置等）
- 支持模拟屏幕尺寸、分辨率等
- 伪装 WebGL 参数、支持的扩展、上下文属性和着色器精度格式
- 伪装窗口内部和外部视口大小
- 伪装 AudioContext 采样率、输出延迟和最大通道数
- 伪装设备语音和播放速率
- 伪装可用的麦克风、摄像头和扬声器数量
- 网络请求头（Accept-Languages 和 User-Agent）会被伪装以匹配 navigator 属性
- 在协议层面进行 WebRTC IP 伪装
- 地理位置、时区和区域设置伪装
- 电池 API 伪装
- 等等。

### 隐身补丁

- 避免主世界执行泄漏。所有页面代理 JavaScript 都在沙箱中运行
- 避免框架执行上下文泄漏
- 修复 `navigator.webdriver` 检测
- 修复通过指针类型检测 Firefox 无头模式的问题（[#26](https://github.com/daijro/camoufox/issues/26)）
- 移除了可能泄漏的反缩放 / meta 视口处理补丁
- 使用非默认的屏幕和窗口尺寸
- 重新启用 fission 内容隔离
- 重新启用 PDF.js
- 其他会导致泄漏的配置属性已更改
- 拟人化光标移动

### 反字体指纹识别

- 自动为你的 User Agent 使用正确的系统字体
- 内置 Windows、Mac 和 Linux 系统字体
- 通过随机调整字距来防止字体度量指纹识别

### Playwright 支持

- 针对最新版 Firefox 的 Playwright 自定义实现
- 多种配置补丁以规避机器人检测

### 精简/优化

- 移除/禁用了 _大量_ Mozilla 服务。运行速度比原始 Mozilla Firefox 更快，占用内存更少（200mb）
- 来自 LibreWolf 和 Ghostery 的补丁，有助于移除遥测和臃肿功能
- 来自 PeskyFox、LibreWolf 等的精简配置
- 来自 FastFox 的速度和网络优化
- 移除了所有 CSS 动画
- 极简主题
- 等等。

### 附加组件

- 通过向 `addons` 属性传入路径列表来加载 Firefox 附加组件，无需调试服务器
- 添加了带自定义隐私过滤规则的 uBlock Origin
- 不允许附加组件打开标签页
- 附加组件会自动在隐私浏览模式下启用
- 附加组件会自动固定到工具栏
- 修复 uBO 预取导致的 DNS 泄漏

### Python 接口

- 根据真实世界分布自动生成并注入独特的设备特征到 Camoufox
- WebGL 指纹注入与轮换
- 根据目标操作系统使用正确的系统字体和次像素抗锯齿及字体微调
- 通过从代理的目标区域计算目标地理位置、时区和区域设置来避免代理检测
- 根据代理目标区域中语言使用者的分布来计算并伪装浏览器语言
- 远程服务器托管，以便在支持 Playwright 的其他语言中使用 Camoufox
- 内置虚拟显示缓冲区，可在无头服务器上以有头模式运行 Camoufox
- 切换图片加载、WebRTC 和 WebGL
- 等等。

> [!NOTE]
> Camoufox **不**完全支持注入 Chromium 指纹。某些 WAF（如 [Interstitial](https://nopecha.com/demo/cloudflare)）会测试 Spidermonkey 引擎行为，这是无法伪装的。

---

# 隐身概览

## Camoufox 如何隐藏其自动化库

> [!WARNING]
> **截至 2026 年的当前状态**：
> 由于个人情况，维护中断了一年。由于基础 Firefox 版本和新发现的指纹不一致问题，Camoufox 的性能有所下降。**Camoufox 目前正在积极开发中。**

在 Camoufox 中，Playwright 内部 Page Agent 的所有代码都被沙箱化并隔离。这使得页面无法通过 JavaScript 检查来检测 Playwright 的存在。

通常，Playwright 会向页面注入一些 JavaScript，例如 `window.__playwright__binding__`，并执行查询元素、评估 JavaScript 或运行初始化脚本等操作，这些都会被网站检测到。在 Camoufox 中，这些操作在页面之外的隔离作用域中处理。换句话说，网站无法再“看到”Playwright 通常会注入的任何 JavaScript。这从根源上杜绝了 Playwright 的痕迹。

然而，即使隐藏了其自动化库，Camoufox 也无法避免指纹轮换中的不一致问题。这仍然需要维护来发现和修复。

### 页面交互

反机器人系统还会运行客户端脚本来监控你的行为。例如，它们会寻找鼠标移动、点击、滚动以及操作之间时间间隔的模式。

<video controls src="https://github.com/user-attachments/assets/6d33d6af-3537-4603-bf24-6bd3f4f8f455" width="200px" loop muted></video>

Camoufox 凭借其拟人化鼠标移动算法尽力而为。自然运动算法最初来自 [riflosnake 的 HumanCursor](https://github.com/riflosnake/HumanCursor)，已用 C++ 重写，并修改为更注重距离感知的轨迹。

然而，这并不完美。如果分析足够复杂，它仍然可能被检测到。（未来待办）

---

## Camoufox 如何轮换身份

AI 代理需要在多个会话中运行，而不会被标记或限流。仅轮换 IP 地址是不够的——每个浏览器会话都会携带数千个信号，从而产生独特的**指纹**。网站可以看到你的操作系统、GPU、屏幕分辨率、字体、时区等信息。如果这些信号不一致或异常，你就会被屏蔽。

### 市场份额分布

即使你为每个运行的机器人实例轮换 IP，Web 访问防火墙仍然可以使用机器学习来分析传入的 Web 流量，以检测其是否异常。如果 Linux 市场份额是 5%，突然变成 20%，那就是一个危险信号。它们会无条件要求所有 Linux 用户完成验证码。

Camoufox 使用 [BrowserForge](https://github.com/daijro/browserforge) 的指纹生成器来模拟真实流量中设备数据的统计分布。例如，Camoufox 会让你的浏览器在 5% 的情况下看起来像 Linux 用户。在这 5% 中，它会在 9.5% 的情况下伪装成 2560x1440 屏幕分辨率，在 27.5% 的情况下伪装成 Intel HD GPU。

### Camoufox 如何被检测到？

Camoufox 可以使用正确的市场份额来伪装指纹。然而，**指纹在内部也必须保持一致。** Windows 用户代理搭配 Apple M1 GPU、MacOS 用户代理搭配 Windows DirectX 渲染器、移动设备搭配桌面屏幕分辨率，这些都是不可能的，会被标记为可疑。

在创建可信的伪装指纹所需更改的数千个可能数据点中，每个更改都必须与其他更改保持一致，Camoufox 并不总能成功。反机器人服务商会反复测试 Camoufox，只为找到哪怕 1 个独有的一致性缺陷，然后立即更新其后端脚本进行检测。

---

## Camoufox 与其他解决方案相比如何？

### 基于 JavaScript 的解决方案

过去，开发者尝试注入 JavaScript 来伪装这些值，但这并不可靠，因为 JavaScript 无法伪装所有内容。覆盖不全会导致指纹不一致。例如，如果你的网络请求的 User Agent 与 navigator 的 User Agent 不匹配，反机器人系统就会标记你。

此外，所有注入的 JavaScript 都以某种方式可被检测。反机器人系统可以检查 `Object.getOwnPropertyDescriptor` 是否暴露了被覆盖的属性、函数的 `toString()` 是否不再返回 `[native code]`（从而暴露其被劫持），或者 window 上下文中的数据是否与 worker 线程上下文不匹配。变通方法只能让你走这么远，但只要你深挖，总有办法检测 JS 注入。

#### Camoufox 的方法

由于 Camoufox 在浏览器的 C++ 实现层面拦截调用，所有被劫持的对象和属性看起来都是原生的。没有 JavaScript 劫持可供检测。

Camoufox 还尝试使用 Browserforge 生成一致且可信的指纹。然而，这仍然可能被复杂指纹检测方法（如数据不匹配，如前所述）检测到。

<hr width=50>

### 基于 CDP 的库

CDP（Chrome DevTools Protocol）是内置于 Chromium 和 Firefox 的自动化协议。然而，CDP 并不试图隐藏它是自动化协议的事实，并在页面作用域中暴露了其大部分功能。一些常见方法包括检查 `navigator.webdriver` 是否为真、捕捉堆栈调试器的读取、检查 ChromeDriver 注入到 document 对象中用于内部通信的变量，等等。

#### Camoufox 的方法

Playwright 使用 CDP 控制 Chromium，但对于 Firefox，它使用的是 _Juggler_。Juggler 是在 Firefox 支持 CDP 之前开发的自定义协议（[原始仓库](https://github.com/puppeteer/juggler)）。它是 Firefox 中的一个独立模块，不属于其核心浏览器的一部分。这使得编辑和控制向页面暴露的内容变得更加容易。

Camoufox 修补了 Juggler，使其拥有一个隔离的页面“副本”来操作。Playwright 可以自由读取和编辑自己的页面版本。对它来说一切看起来都正常工作，但真实页面完全不受这些更改的影响。页面也无法检测到正在被读取的内容（通过劫持 getter 等手段）或正在添加的用于监视元素的监听器。

此外，Juggler 直接通过 Firefox 原始的用户输入处理程序发送其输入，这意味着它们的处理方式与正常使用浏览器时完全相同。Camoufox 还修补了 Firefox 的无头模式，使其看起来与在普通窗口中运行相同。但作为后备方案，如果无头模式出现泄漏，Python 库可以在[虚拟显示](https://camoufox.com/python/virtual-display/)中运行 Camoufox。

---

<h1 align="center">构建系统</h1>

> [!WARNING]
> 以下内容面向对构建和调试 Camoufox 感兴趣的人。有关 Playwright 使用说明，请参阅[此处](https://github.com/daijro/camoufox/tree/main/pythonlib#camoufox-python-interface)。

### 概述

以下是构建系统及其相关 make 命令的示意图：```mermaid
graph TD
    FFSRC[Firefox Source] -->|make fetch| REPO

    subgraph REPO[Camoufox Repository]
        PATCHES[Fingerprint masking patches]
        ADDONS[uBlock & B.P.C.]
        DEBLOAT[Debloat/optimizations]
        SYSTEM_FONTS[Win, Mac, Linux fonts]
        JUGGLER[Patched Juggler]
    end

    subgraph Local
    REPO -->|make dir| PATCH[Patched Source]
    PATCH -->|make build| BUILD[Built]
    BUILD -->|make package-linux| LINUX[Linux Portable]
    BUILD -->|make package-windows| WIN[Windows Portable]
    BUILD -->|make package-macos| MAC[macOS Portable]
    end

接下来，使用以下命令构建 Camoufox 源代码：```bash
make dir

> [!NOTE]
> 依赖项安装程序目前仅在 macOS 上测试过。

之后，你需要引导（bootstrap）系统以便能够构建 Camoufox。你只需执行一次。通过运行以下命令来完成：```bash
make bootstrap

对于新构建，`i686` 仅支持 Windows。不支持的目标/架构组合将被跳过。

<details>
<summary>
命令行参数
</summary>```bash
Options:
  -h, --help            show this help message and exit
  --target {linux,windows,macos} [{linux,windows,macos} ...]
                        Target platforms to build
  --arch {x86_64,arm64,i686} [{x86_64,arm64,i686} ...]
                        Target architectures to build for each platform
  --bootstrap           Bootstrap the build system
  --clean               Clean the build directory before starting

Example:
$ python3 multibuild.py --target linux windows macos --arch x86_64 arm64

2. 为目标平台和架构构建 Camoufox 补丁：```bash
docker run -v "$(pwd)/dist:/app/dist" camoufox-builder --target <os> --arch <arch>

补丁可以在这里编辑、创建、移除和管理。

<img src="https://assets.kitploit.com/production/public/readmes/41473/19bffc384c42fb6eb69b3ee59622daed4770cf0f11ffe39401eca57a7d2457f4.png">

### 如何制作补丁

1. 在开发者界面中，点击 **重置工作区**。
2. 根据需要修改 `camoufox-*/` 文件夹中的内容。你可以使用 `make build` 和 `make run` 测试你的更改。
3. 完成修改后，点击 **将工作区写入补丁** 并保存补丁文件。

### 如何处理现有补丁

1. 在开发者界面中，点击 **编辑补丁**。
2. 选择要编辑的补丁。你的工作区将重置为所选补丁的状态。
3. 完成修改后，点击 **将工作区写入补丁** 并覆盖现有的补丁文件。

---

## 泄漏调试

这是一个流程图，展示了我在不反混淆 WAF Javascript 的情况下确定泄漏的过程。该方法逐步将 Camoufox 的功能重新引入 Firefox 的源代码，直到测试站点触发标记。

此过程需要 Linux 系统，并假定你已安装 Firefox 构建工具（参见[此处](https://github.com/daijro/camoufox?tab=readme-ov-file#build-cli)）。

<details>
<summary>
查看流程图...
</summary>```mermaid
flowchart TD
    A[Start] --> B[Does website flag in the official Firefox?]
    B -->|Yes| C[Likely bad IP/rate-limiting. If the website fails on both headless and headful mode on the official Firefox distribution, the issue is not with the browser.]
    B -->|No| D["Run make ff-dbg(1) and build(2) a clean distribution of Firefox. Does the website flag in Firefox **headless** mode(4)?"]
    D -->|Yes| E["Does the website flag in headful mode(3) AND headless mode(4)?"]
    D -->|No| F["Open the developer UI(5), apply config.patch, then rebuild(2). Does the website still flag(3)?"]
    E -->|No| G["Enable privacy.resistFingerprinting in the config(6). Does the website still flag(3)?"]
    E -->|Yes| C
    G -->|No| H["In the config(6), enable FPP and start omitting overrides until you find the one that fixed the leak."]
    G -->|Yes| I[If you get to this point, you may need to deobfuscate the Javascript behind the website to identify what it's testing.]
    F -->|Yes| K["Open the developer UI, apply the playwright bootstrap patch, then rebuild. Does it still flag?"]
    F -->|No| J["Omit options from camoufox.cfg(6) and rerun(3) until you find the one causing the leak."]
    K -->|No| M[Juggler needs to be debugged to locate the leak.]
    K -->|Yes| L[The issue has nothing to do with Playwright. Apply the rest of the Camoufox patches one by one until the one causing the leak is found.]
    M --> I