blockads-android README

项目的 README,来自 github.com/pass-with-high-score/blockads-android。合并为一个 markdown 文件:README.md。

BlockAds

BlockAds is a free, open-source ad blocker for Android.

It blocks ads, trackers, and malware system-wide using local VPN-based DNS filtering — no root required, no data collection.

Built with Jetpack Compose and Material 3 for a modern, premium experience.





Download

Get it on F-Droid

Get it at IzzyOnDroid

Screenshots


Features


Community

Join our community:
Reddit Telegram

Sponsor

If you enjoy BlockAds, consider supporting the project! Your sponsorship helps us maintain and improve the app.

Sponsor

Build Instructions

Requirements

Steps

[!TIP] Historical versions of the Go binary (tunnel.aar) were committed in the past before being moved to GitHub Releases. To avoid downloading ~1.2GB of old binaries, use blobless clone (--filter=blob:limit=1m) to download only ~20MB.

  1. Clone the repository:

    git clone --filter=blob:limit=1m https://github.com/pass-with-high-score/blockads-android.git
    cd blockads-android
    

    (Or for a shallow clone: git clone --depth=1 https://github.com/pass-with-high-score/blockads-android.git)

  2. (Optional) Build the Go tunnel AAR/JAR from source (with Android 15 16KB page size support):

    ./scripts/build_tunnel.sh
    # Or
    ./gradlew -Ptunnel.source=local buildGoTunnel
    

    Note: This is completely optional. Gradle automatically resolves a prebuilt, checksum-pinned tunnel.aar from GitHub Releases by default. You do not need Go or NDK unless you are modifying Go code in tunnel/. See docs/TUNNEL.md.

  3. Open the project in Android Studio

  4. Sync Gradle and run the app on a device or emulator

  5. Build from command line:

    ./gradlew assembleDebug
    ./gradlew bundleRelease   # requires signing key
    

How It Works

BlockAds routes DNS queries locally either through a VpnService (Vpn Mode) or via iptables redirection (Root Proxy Mode). These queries are matched against loaded filter lists using a memory-efficient Trie data structure. Matching queries are blocked locally, while all other traffic passes through normally — no data leaves your device.

When HTTPS Filtering is enabled, a userspace TCP/IP stack (gVisor netstack via tun2socks) terminates each TCP/UDP flow in Go, looks up the owning app UID via Android's ConnectivityManager.getConnectionOwnerUid(), and only MITMs flows from selected browsers. Cert-pinned apps and the 284-domain curated passthrough list bypass MITM cleanly. Cosmetic CSS rules and EasyList ##+js(…) / AdGuard #%#//scriptlet(…) scriptlets are injected into HTML responses via a tiny in-memory local asset host.


License

This project is licensed under the GNU General Public License v3.0.
You are free to use, modify, and distribute it under the terms of the license.
See the full LICENSE file for details.


Credits


Contributing

Pull requests and issue reports are welcome.
Help us improve BlockAds!

Help us translate BlockAds

Want to see BlockAds in your language?
Open an issue or submit a PR with your translations.


Star History

Star History Chart

blockads-android (pass-with-high-score/blockads-android)

正在搜索数据库…

这是什么?BlockAds 是一款免费开源的 Android 应用。它通过运行本地 VPN 过滤 DNS 查询,在全系统范围内拦截广告、追踪器和恶意软件。无需 root 权限,数据也不会离开设备。
我该怎么把它跑起来?克隆仓库,用 Android Studio 打开项目,同步 Gradle,然后在真机或模拟器上运行。你也可以通过命令行构建。
编译这个项目需要装 Go 或 Android NDK 吗?不需要。Gradle 会自动从 GitHub Releases 拉取预编译好、带校验和固定的 tunnel.aar。只有想自己修改 Go 隧道代码时,才需要 Go 和 NDK。否则,Android Studio、JDK 17+ 和 Android SDK 36 就够了。
HTTPS 过滤功能有什么限制吗?HTTPS 过滤功能运行的是用户态 TCP/IP 协议栈,只拦截来自指定浏览器的数据流。此外,一份精选的 284 个银行、支付和政务域名列表,以及使用证书固定的应用,都会完全绕过拦截,以免它们出错。
我的浏览数据会去哪里?所有数据都保留在设备上。DNS 匹配在本地完成,崩溃报告和遥测功能严格采用选择加入,需要你主动开启。
内置了哪些过滤规则列表?它内置了多个精选列表,例如 StevenBlack、AdGuard DNS 和 EasyList。它还提供区域感知的默认设置,会根据设备语言自动启用匹配的过滤规则。
我得给手机 root 才能用吗?不需要。默认的 Vpn Mode 通过 Android 的 VpnService 在全系统范围内拦截广告,无需 root。另外还提供基于 iptables 的 Root Proxy Mode,供已 root 的设备使用。
它怎么过滤 HTTPS 流量,又不会破坏浏览器的安全提示?它会安装一个本地 CA 证书,并进行安装校验和自动刷新检查。这样,它的用户态 TCP 协议栈就能处理来自指定浏览器的 HTTPS 数据流。它还会注入外观过滤用的 CSS 规则,以及 EasyList/AdGuard 的 scriptlet。
我能在去广告的同时导入自己的 WireGuard 配置吗?可以。WireGuard 配置导入是内置功能,你可以把自己的 WireGuard 配置和 BlockAds 的过滤功能结合使用。
大小
1.1 GB
星标
2.8K
时长
9个月
提交 · 90 天