M-Abozaid/esp32-c3-adblock

这是什么？

核心功能

• 01通过 UDP DNS 对拦截域名返回 0.0.0.0，其他请求转发至上游。
• 02黑名单以 40 位哈希存于闪存，约占用 50 KB RAM，无需 PSRAM。
• 03Web 管理面板可查看各客户端拦截次数，并手动封禁或添加自定义域名。
• 04支持 WiFi 固件与黑名单在线升级，并可定时拉取远程黑名单。
• 05提供 Captive Portal 形式的 WiFi 配网，并通过 mDNS 访问 c3adblock.local。
• 06黑名单构建脚本支持 hosts 文件、纯域名列表和 AdGuard 基础规则。

适用场景

• 在家庭网络中低成本实现全网广告和追踪域名拦截，无需树莓派。
• 作为主 DNS 之后的低功耗备用解析器，拦截指定域名。
• 在廉价的 ESP32-C3 开发板上学习或实验嵌入式 DNS 过滤。

快速上手

1. 1

   复制密钥模板并编辑 WiFi 和控制台凭据

   cp src/secrets.example.h src/secrets.h
2. 2

   生成屏蔽列表哈希表

   python3 tools/build_blocklist.py data/blocklist.bin
3. 3

   通过 USB 将固件烧录到 ESP32-C3

   pio run -t upload
4. 4

   通过 USB 烧录屏蔽列表文件系统

   pio run -t uploadfs

使用前须知

• !需要较新的 PlatformIO，旧版 apt 包会编译失败。
• !在 4 MB 闪存上，固件 OTA 更新会将屏蔽列表限制在约 25 万个域名。
• !必须在 secrets.h 中设置控制台和 OTA 密码，否则设备会使用公开的默认凭据启动。
• !流量为明文 HTTP 并使用 Basic 认证，局域网内不加密。

收录于专题

标签

常见问题

esp32-c3-adblock 是什么？

面向 2 美元 ESP32-C3 的 Pi-hole 式 DNS 广告拦截器，黑名单以哈希形式存于闪存，无需 PSRAM。 esp32-c3-adblock 把一块小型 ESP32-C3 开发板变成网络级 DNS 黑洞。局域网内的设备将 DNS 指向该板子，被拦截的域名返回 0.0.0.0，其他请求则转发给上游解析器。

esp32-c3-adblock 可以免费使用吗？用的什么许可证？

esp32-c3-adblock 以 MIT 许可证开源。用于商业产品前，请先确认许可证条款。

esp32-c3-adblock 还在维护吗？

活跃维护中。esp32-c3-adblock 最近一次提交是在 2026年11月6日。

esp32-c3-adblock 适合用来做什么？

在家庭网络中低成本实现全网广告和追踪域名拦截，无需树莓派。 作为主 DNS 之后的低功耗备用解析器，拦截指定域名。 在廉价的 ESP32-C3 开发板上学习或实验嵌入式 DNS 过滤。

esp32-c3-adblock 怎么安装和运行？

复制密钥模板并编辑 WiFi 和控制台凭据: cp src/secrets.example.h src/secrets.h 生成屏蔽列表哈希表: python3 tools/build_blocklist.py data/blocklist.bin 通过 USB 将固件烧录到 ESP32-C3: pio run -t upload 通过 USB 烧录屏蔽列表文件系统: pio run -t uploadfs

在哪里获取 esp32-c3-adblock？

源代码和安装说明在 GitHub 上：https://github.com/M-Abozaid/esp32-c3-adblock