# @adguard/hostlist-compiler 中文文档 规范地址：https://npmcn.com/package/%40adguard/hostlist-compiler/ 版本：2\.1\.1 npm 元数据更新时间：2026-08-22T09:45:54.913Z 中文译文更新时间：2026-11-06T02:27:35.190Z 软件包许可：GPL-3\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40adguard/hostlist-compiler 原文对照：https://npmcn.com/package/%40adguard/hostlist-compiler/?lang=original 项目主页：https://github.com/AdguardTeam/HostlistCompiler#readme 源码仓库：https://github.com/AdguardTeam/HostlistCompiler ## 关键信息（来自 npm 元数据） - 包体积（解压后）：281 kB，75 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - 运行依赖：9 个 - 首次发布：2020-03-11T16:56:33.931Z - 最新版本发布：2026-08-22T09:45:54.751Z - 近 30 天下载量：6410（2026-10-05 至 2026-11-03，npm 官方下载统计） - 已发布版本数：34（近 12 个月 3 个） ## 中文简介 从多个来源汇编主机块列表的简单工具 ## 安装 ```sh npm install @adguard/hostlist-compiler ``` 也可以使用：`pnpm add @adguard/hostlist-compiler`、`yarn add @adguard/hostlist-compiler`、`bun add @adguard/hostlist-compiler` ## README # 主机列表编译器 [![NPM](https://nodei.co/npm/@adguard/hostlist-compiler.png?compact=true)](https://www.npmjs.com/package/@adguard/hostlist-compiler/) 这是一个简单的工具,可以更容易编译 [主机块列表](https://adguard-dns.io/kb/general/dns-filtering-syntax/) 与AdGuard Home或任何其他AdGuard产品兼容 **DNS 过滤**。 。 。 . > **关于储存库的说明:** 积极发展发生在私人 [辅助软件Limited/filters-hostlist-编译器](https://github.com/AdGuardSoftwareLimited/filters-hostlist-compiler) 寄存器; 此公开 [守护小组/主机编制器](https://github.com/AdguardTeam/HostlistCompiler) 寄存器是一个只读的镜像,从中自动更新. - [使用量](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-usage) - [配置](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-configuration) - [命令行](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-command-line) - [API 密码](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-api) - [转换](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-transformations) - [转换到Ascii](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-convert-to-ascii) - [三角线](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-trimlines) - [删除注释](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-remove-comments) - [压缩](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-compress) - [删除修改器](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-remove-modifiers) - [反转Allow](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-invertallow) - [校验](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-validate) - [校验 AllowIp](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-validate-allow-ip) - [验证 Allow 公共后缀](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-validate-allow-public-suffix) - [验证 AllowIpAnd Public 后缀](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-validate-allow-ip-and-public-suffix) - [重复](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-deduplicate) - [删除线](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-removeemptylines) - [插入最后新线](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-insertfinalnewline) - [文档](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-documentation) ## 使用量 首先,安装 `hostlist-compiler`数字 : ```bash npm i -g @adguard/hostlist-compiler ``` 之后你有两个选择. **快速主机转换** 转换和压缩 a `/etc/hosts`\- 语法块列表到 [守护语法](https://adguard-dns.io/kb/general/dns-filtering-syntax/)。 。 。 . ``` hostlist-compiler -i hosts.txt -i hosts2.txt -o output.txt ``` **从多个来源建立可配置的块列表** 准备列表配置( 更多信息 ) [下级](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-configuration))并运行编译器: ```bash hostlist-compiler -c configuration.json -o output.txt ``` **所有命令行选项** ``` Usage: hostlist-compiler [options] Options: --config, -c Path to the compiler configuration file [string] --input, -i URL (or path to a file) to convert to an AdGuard-syntax blocklist. Can be specified multiple times. [array] --input-type, -t Type of the input file (/etc/hosts, adguard) [string] --output, -o Path to the output file [string] [required] --verbose, -v Run with verbose logging [boolean] --version Show version number [boolean] -h, --help Show help [boolean] Examples: hostlist-compiler -c config.json -o compile a blocklist and write the output.txt output to output.txt hostlist-compiler -i compile a blocklist from the URL and https://example.org/hosts.txt -o write the output to output.txt output.txt ``` ### 配置 配置定义您的过滤列表源, 以及应用到源上的转换 . 以下是此配置的一个例子: ```json { "name": "List name", "description": "List description", "homepage": "https://example.org/", "license": "GPLv3", "version": "1.0.0.0", "sources": [ { "name": "Local rules", "source": "rules.txt", "type": "adblock", "transformations": ["RemoveComments", "Compress"], "exclusions": ["excluded rule 1"], "exclusions_sources": ["exclusions.txt"], "inclusions": ["*"], "inclusions_sources": ["inclusions.txt"] }, { "name": "Remote rules", "source": "https://example.org/rules", "type": "hosts", "exclusions": ["excluded rule 1"] } ], "transformations": ["Deduplicate", "Compress"], "exclusions": ["excluded rule 1", "excluded rule 2"], "exclusions_sources": ["global_exclusions.txt"], "inclusions": ["*"], "inclusions_sources": ["global_inclusions.txt"] } ``` - `name` - (强制性)名单名称. - `description` - (可选)列表描述. - `homepage` - (可选)列表主页的 URL . - `license` - (可选)过滤列表许可证. - `version` - (可选)过滤器列表版本. - `sources` - 列表来源的(强制性)数组. - `.source` - 来源的(强制性)路径或URL。 它可以是传统的过滤列表或主机文件. - `.name` -(可选)来源名称. - `.type` - 来源的(可选)类型。 这可能是 `adblock` 用于块状列表或 `hosts` 用于/etc/hosts样式列表。 如未指明, `adblock` 假设. - `.transformations` - (可选)适用于源规则的转换列表。 默认, **无变换** 适用。 更多地了解可能的转变 [这里](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-transformations)。 。 。 . - `.exclusions` - (可选的)规则列表(或通配符)以排除来源. - `.exclusions_sources` - (可选的)包含排除内容的文件列表. - `.inclusions` - (可选)包含来自源代码的通配符列表. 所有与这些通配符不相匹配的规则都不会包含在内. - `.inclusions_sources` - (可选)包含内容的文件列表. - `transformations` - (可选)适用于最终规则清单的转换列表。 默认, **无变换** 适用。 更多地了解可能的转变 [这里](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-transformations)。 。 。 . - `exclusions` - (可选的)规则列表(或通配符)以排除来源. - `exclusions_sources` - (可选的)包含排除内容的文件列表. - `.inclusions` - (可选)包含来自源代码的通配符列表. 所有与这些通配符不相匹配的规则都不会包含在内. - `.inclusions_sources` - (可选)包含内容的文件列表. 以下是一个最小配置的例子: ```json { "name": "test list", "sources": [ { "source": "rules.txt" } ] } ``` **不适用和列入规则** 请注意,排除或纳入规则可能是一种平庸的字符串、通配符或正则表达式. - `plainstring` - 所有包含 `plainstring` 将会符合规则 - `*.plainstring` - 每条规则都符合通配符规则 - `/regex/` – 符合此正则表达式的规则, 都会符合规则 。 默认情况下,正则表达式为对大小写不敏感. - `! comment` - 评论将被忽略. > \[大 确保排除列表中的规则与过滤列表中的规则格式相匹配. 为保持统一格式,请添加 `Compress` 转换为转换 `/etc/hosts` 用于阻塞语法的规则. 如果有多个不同格式的列表,则这样做特别有用. 以下是一个例子: HOSTS语法规则 : `/hosts.txt` ```txt 0.0.0.0 ads.example.com 0.0.0.0 tracking.example1.com 0.0.0.0 example.com ``` 街区语法中的排除规则: `/exclusions.txt` ```txt ||example.com^ ``` 最后列表的配置 : ```json { "name": "List name", "description": "List description", "sources": [ { "name": "HOSTS rules", "source": "hosts.txt", "type": "hosts", "transformations": ["Compress"] } ], "transformations": ["Deduplicate", "Compress"], "exclusions_sources": ["exclusions.txt"] } ``` 最后过滤输出 `/hosts.txt` 应用后 `Compress` 变革和排斥: ```txt ||ads.example.com^ ||tracking.example1.com^ ``` 现在最后一个规则 `||example.com^` 将正确匹配排除名单中的规则,并被排除在外. ### 命令行 命令行参数. ``` Usage: hostlist-compiler [options] Options: --version Show version number [boolean] --config, -c Path to the compiler configuration file [string] [required] --output, -o Path to the output file [string] [required] --verbose, -v Run with verbose logging [boolean] -h, --help Show help [boolean] Examples: hostlist-compiler -c config.json -o compile a blocklist and write the output.txt output to output.txt ``` ### API 密码 安装 : `npm i @adguard/hostlist-compiler` 或者说 `yarn add @adguard/hostlist-compiler` #### JavaScript 示例 : ```javascript const compile = require("@adguard/hostlist-compiler"); ;(async () => { // Compile filters const result = await compile({ name: 'Your Hostlist', sources: [ { type: 'adblock', source: 'https://adguardteam.github.io/AdGuardSDNSFilter/Filters/filter.txt', // or local file transformations: ['RemoveComments', 'Validate'], }, ], transformations: ['Deduplicate'], }); // Write to file writeFileSync('your-hostlist.txt', result.join('\n')); })(); ``` #### 类型脚本示例 : ```typescript import compile from '@adguard/hostlist-compiler'; import { writeFileSync } from 'fs'; ;(async () => { // Compile filters const result = await compile({ name: 'Your Hostlist', sources: [ { type: 'adblock', source: 'https://adguardteam.github.io/AdGuardSDNSFilter/Filters/filter.txt', transformations: ['RemoveComments', 'Validate'], }, ], transformations: ['Deduplicate'], }); // Write to file writeFileSync('your-hostlist.txt', result.join('\n')); })(); ``` 或: ```typescript import HostlistCompiler, { IConfiguration as HostlistCompilerConfiguration } from '@adguard/hostlist-compiler'; import { writeFileSync } from 'fs'; ;(async () => { // Configuration const config: HostlistCompilerConfiguration = { name: 'Your Hostlist', sources: [ { type: 'adblock', source: 'https://adguardteam.github.io/AdGuardSDNSFilter/Filters/filter.txt', transformations: ['RemoveComments', 'Validate'], }, ], transformations: ['Deduplicate'], }; // Compile filters const result = await HostlistCompiler(config); // Write to file writeFileSync('your-hostlist.txt', result.join('\n')); })(); ``` ## 转换 以下列出可用的全部变换列表: 1. `ConvertToAscii` 2. `TrimLines` 3. `RemoveComments` 4. `Compress` 5. `RemoveModifiers` 6. `InvertAllow` 7. `Validate` 8. `ValidateAllowIp` 9. `ValidateAllowPublicSuffix` 10. `ValidateAllowIpAndPublicSuffix` 11. `Deduplicate` 12. `RemoveEmptyLines` 13. `InsertFinalNewLine` 请注意,这些转变总是按此处所指明的顺序进行. ### 转换到Ascii 这个转换将所有非 ASCII 字符转换为它们的 ASCII 等同. 总是先做. **示例** 原名单: ``` ||*.рус^ ||*.कॉम^ ||*.セール^ ``` 接下来,我们实施这一转变后 ``` ||*.xn--p1acf^ ||*.xn--11b4c3d^ ||*.xn--1qqw23a^ ``` ### 三角线 这是一个非常简单的转换,它去除了前导和后导的空间/tab. **示例** 原名单: ``` rule1 rule2 rule3 rule4 ``` 接下来,我们实施这一转变后 ``` rule1 rule2 rule3 rule4 ``` ### 删除注释 这是一个非常简单的转换,它简单地删除了注释(例如,所有规则从 `!` 或者说 `#`) (中文(简体) ). ### 压缩 > \[大 此转换转换 `hosts` 列表为 `adblock` 列表. 这就是它的作用: 1. 它将所有的规则转换为"块"式的规则. 比如说, `0.0.0.0 example.org` 将转换为 `||example.org^`。 。 。 . 2. 它抛弃了现在由于其他现有规则而多余的规则. 比如说, `||example.org` 块 `example.org` 和所有它都是子域, 因此附加规则 对于子域现在冗余. ### 删除修改器 默认, [守护之家](https://github.com/AdguardTeam/AdGuardHome) 将忽略不支持的修改符的规则,这里列出的所有修改符都是不支持的. 然而,带有这些修饰符的规则对于DNS级阻塞很可能是好的,所以在从传统的过滤器列表中导入规则时,你可能会想将其删除. 以下列出将删除的修饰符: - `$third-party` 财务报告和审定财务报表 `$3p` 修改 - `$document` 财务报告和审定财务报表 `$doc` 修改 - `$all` 修改 - `$popup` 修改 - `$network` 修改 > \[叹息\] 盲目清除 `$third-party` 从传统的广告封锁规则 导致很多虚假阳性. > > > 这正是为什么有 排除规则的选择 - 你可能需要使用它. ### 反转Allow 这种转换将阻塞规则转换为"允许"规则. 注意,它对/etc/hosts规则没有任何作用(除非它们以前通过不同的转换转换转换为adblock-tyle语法,例如: [压缩](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-compress)) (中文(简体) ). 关于这种转变,有两个重要的说明: 1. 它维持了原有的规则秩序. 2. 它忽略了评论,空行,/etc/host规则和已存在的"允许"规则. **示例** 原名单: ``` ! comment 1 rule1 # comment 2 192.168.11.11 test.local @@rule2 ``` 接下来,我们实施这一转变后 ``` ! comment 1 @@rule1 # comment 2 192.168.11.11 test.local @@rule2 ``` ### 校验 如果你把一个过滤列表 用于传统的广告屏蔽器作为源头,这个转换就非常关键. 它将危险或不相容的规则从清单中删除. 这就是它的作用: - 丢弃特定域规则(如. `||example.org^$domain=example.com`) (中文(简体) ). 你不想让特定领域的规则在全球运作. - 以不支持的修饰符丢弃规则. [点击这里](https://github.com/AdguardTeam/AdGuardHome/wiki/Hosts-Blocklists#-adblock-style-syntax) 以便更多地了解支持哪些修饰者. - 抛弃那些太短的规则. - 丢弃IP地址. 如果您需要保留 IP 地址, 请使用 [校验 AllowIp](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-validate-allow-ip) 换句话说. #### 被拒绝的 IP 模式 下列IP模式被所有验证转换所拒绝(`Validate`, (中文(简体) ), `ValidateAllowIp`, (中文(简体) ), `ValidateAllowPublicSuffix`, (中文(简体) ), `ValidateAllowIpAndPublicSuffix`它们要么不安全,要么含糊不清: - `||192.168.1^` - 3-ott 与 `^` - 没用 - `192.168.1` - 模棱两可: `192.168.11`, (中文(简体) ), `192.168.111`等 (中文(简体) ). - `1.2.` 或者说 `1.2.*` - 宽度太高(1至2octets),取而代之的是正则克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克 - 删除阻碍整个顶级域( TLD) 的规则 `||*.org^`,除非它们有特定的限制性修改语,例如: `$denyallow`, (中文(简体) ), `$badfilter`,或 `$client`。 。 。 . 实例: - `||*.org^` - 这条规则将被删除 - `||*.org^$denyallow=example.com` - 这条规则会被保留 因为它有一个限制修改符 如果必须保存这些规则,请使用 [验证 Allow 公共后缀](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-validate-allow-public-suffix) 或者说 [验证 AllowIpAnd Public 后缀](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-validate-allow-ip-and-public-suffix)。 。 。 . 如果在无效规则之前有评论,也将被删除. ### 校验 AllowIp 此转换延伸 [校验](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-validate) 以允许列表中的 IP 地址。 还有 **使IP规则正常化** 以 Adblock 样式改为安全格式 `||ip^`。 。 。 . #### IP 规则正常化 - `1.2.3.4` → `||1.2.3.4^` (添加两个分隔符) - `1.2.3.4^` → `||1.2.3.4^` (添加左锚) - `|1.2.3.4` → `||1.2.3.4^` (替换) `|` 与 `||`,添加 `^`(中文(简体) ) - `|1.2.3.4^` → `||1.2.3.4^` (替换) `|` 与 `||`(中文(简体) ) - `||1.2.3.4` → `||1.2.3.4^` (添加右分隔符) - `||1.2.3.4^` ~ (没有变化,已经可以了) - `192.168.1.` → `||192.168.1.` (3-octet子网通配符) - `192.168.1.*` → `||192.168.1.*` (3-octet子网通配符) 修饰者喜欢 `$important`, (中文(简体) ), `$client`, (中文(简体) ), `$denyallow`, (中文(简体) ), `$badfilter` 在正常化期间予以保留. > **说明:** 无效的 IP 模式只被基数拒绝 [校验](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-validate) 逻辑——正常化只将有效模式转换为犬形,其他一切通过不变. 见 [被拒绝的 IP 模式](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-rejected-ip-patterns) 详细情况. ### 验证 Allow 公共后缀 这种转变完全重复了 [校验](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-validate),但留下了与整个公共后缀相匹配的规则(例如. `||hl.cn^`, (中文(简体) ), `||org^`在列表中. 它仍然会过滤出无效的语法规则和不支持的修饰者,但不会拒绝公共后缀规则,除非规则本身是错的. > **说明:** 组合任意 `Validate`, (中文(简体) ), `ValidateAllowIp`, (中文(简体) ), `ValidateAllowPublicSuffix`,以及 `ValidateAllowIpAndPublicSuffix` 在一个变换列表中不允许并将导致出错。 每一个在上一个已过滤的输出上运行自己的验证器,所以允许-modes变得默默无效. > **重要内容:** 验证转换也不能同时用于源一级和上一级. 例如,如果一个源使用 `ValidateAllowPublicSuffix` 并使用顶级配置 `Validate`,编译器将丢出一个错误。 这是因为高层 `Validate` 将取代源级验证,生成 `ValidateAllowPublicSuffix` 无效。 仅在一个级别使用验证转换. ### 验证 AllowIpAnd Public 后缀 这种转变结合了 [校验 AllowIp](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-validate-allow-ip) 财务报告和审定财务报表 [验证 Allow 公共后缀](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-validate-allow-public-suffix). 它既允许IP地址,也允许列表中的公共后缀规则. 喜欢 `ValidateAllowIp`,它将不完整的IP规则与安全格式正常化 `||ip^` 在验证之前。 见 [IP 规则正常化](https://npmcn.com/package/%40adguard/hostlist-compiler/#readme-ip-rule-normalization) 详细情况. 喜欢 `ValidateAllowPublicSuffix`,它保持了与整个公共后缀相匹配的规则(例如. `||hl.cn^`, (中文(简体) ), `||org^`) (中文(简体) ). ### 重复 此转换只是从指定的源中去除重复. 关于这种转变,有两个重要的说明: 1. 它维持了原有的规则秩序. 2. 它忽略了评论。 但是,如果评论在删除的规则之前,评论也将被删除. 例如: ``` ! rule1 comment 1 rule1 ! rule1 comment 2 rule1 ``` 变身后剩下的是: ``` ! rule1 comment 2 rule1 ``` ### 删除线 这是一个非常简单的转换,可以去除空行. **示例** 原名单: ``` rule1 rule2 rule3 ``` 接下来,我们实施这一转变后 ``` rule1 rule2 rule3 ``` ### 插入最后新线 这是一个非常简单的转换,它插入了最后的新行. **示例** 原名单: ``` rule1 rule2 rule3 ``` 接下来,我们实施这一转变后 ``` rule1 rule2 rule3 ``` `RemoveEmptyLines` 由于执行命令,不删除此空行. ## 文档 - [发展指南](https://npmcn.com/package/%40adguard/hostlist-compiler/DEVELOPMENT.md) ——如何营造环境,建设,试验和贡献 - [LLM 代理规则](https://npmcn.com/package/%40adguard/hostlist-compiler/AGENTS.md) 守则准则和项目公约 - [更改日志](https://npmcn.com/package/%40adguard/hostlist-compiler/CHANGELOG.md) ——发布历史 ## 常见问题 ### @adguard/hostlist-compiler 是什么？ 从多个来源汇编主机块列表的简单工具 ### 如何安装 @adguard/hostlist-compiler？ 在项目目录运行 npm install @adguard/hostlist-compiler，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 hostlist-compiler，可以用 npx hostlist-compiler 直接运行。 ### @adguard/hostlist-compiler 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @adguard/hostlist-compiler 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @adguard/hostlist-compiler 可以商用吗？ @adguard/hostlist-compiler 使用 GPL-3\.0 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以 GPL-3\.0 兼容许可开源，并附带专利与反锁定条款。仅内部使用不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。 ### @adguard/hostlist-compiler 的下载量有多少？ 根据 npm 官方下载统计，@adguard/hostlist-compiler 在 2026/10/05 – 2026/11/03 这 30 天内被下载 6,410 次，日均约 214 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @adguard/hostlist-compiler 还在维护吗？ 最新版本 2\.1\.1 发布于 2026/08/22（2 个月前）；至今共发布 34 个版本，其中过去 12 个月发布了 3 个；首次发布于 2020/03/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。