Skip to content

配置实战 ​

Config 是 html 库的统一配置结构体,共 31 个字段。多数场景只需选一个预设,再按需覆写字段;完整字段说明见 API 参考 — 配置。

四种预设配置 ​

预设适用场景关键差异
DefaultConfig()通用提取全功能开启,安全默认值
HighSecurityConfig()不受信任输入缩小限制、启用审计、降低深度上限
TextOnlyConfig()仅需纯文本关闭全部媒体保留
MarkdownConfig()内联 Markdown 输出图片与链接按 Markdown 格式渲染
go
package main

import (
	"fmt"
	"log"

	"github.com/cybergodev/html"
)

func main() {
	data := []byte(`<html><body><h1>标题</h1><p>正文内容</p></body></html>`)

	// 大多数场景:直接用默认配置
	p1, err := html.New()
	if err != nil {
		log.Fatal(err)
	}
	defer p1.Close()
	r1, err := p1.Extract(data)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(r1.Title)
	// 输出:标题

	// 只需要纯文本(如搜索引擎索引)
	p2, err := html.New(html.TextOnlyConfig())
	if err != nil {
		log.Fatal(err)
	}
	defer p2.Close()

	// 图片与链接以 Markdown 内联格式出现在 Text 中(如 CMS 迁移)
	p3, err := html.New(html.MarkdownConfig())
	if err != nil {
		log.Fatal(err)
	}
	defer p3.Close()
	r3, err := p3.Extract(data)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(r3.Text)
	// 输出:# 标题
	//       正文内容
}

零值 Config 不可用

Config{} 无法通过 Validate()(MaxInputSize 等字段必须为正数),不要从零值开始。先取一个预设,再覆盖字段。

go
cfg := html.HighSecurityConfig()
cfg.PreserveImages = false // 在高安全基础上额外关闭图片
processor, _ := html.New(cfg)

TextOnlyConfig() 只把 PreserveImages/PreserveLinks/PreserveVideos/PreserveAudios 设为 false,不影响 ExtractAllLinks 的 Include* 过滤。

MarkdownConfig() 只设 InlineImageFormat 与 InlineLinkFormat;ExtractToMarkdown 固定使用 markdown 格式,无需该预设。

六大类字段导览 ​

资源管理 ​

影响内存与吞吐。默认值适用于多数场景,可按负载调整。

字段默认值说明
MaxInputSize50 MB最大输入大小,防止内存耗尽
MaxCacheEntries2000缓存条目数上限;设 0 禁用缓存
CacheTTL1 小时缓存存活时间
CacheCleanup5 分钟后台清理过期缓存的间隔
WorkerPoolSize4批量处理并发数(1–256)
ProcessingTimeout30 秒单文档处理超时;设 0 不限时

缓存仅对 Processor 实例生效

包级函数(如 html.Extract)每次调用都用池化或临时 Processor,缓存不跨调用保留。需要缓存请用 html.New() 创建独立 Processor。详见 Processor 复用与缓存。

安全 ​

生产环境必须关注这一组。完整特性见 安全概述。

字段默认值说明
EnableSanitizationtrueHTML 清洗(移除危险标签/属性)
MaxDepth500DOM 嵌套深度上限,防止栈溢出
AllowedBaseDir""文件操作沙箱目录;空 = 不限制
Audit禁用安全审计日志配置

AllowedBaseDir 与用户提供的路径

文件路径来自用户输入时必须设置 AllowedBaseDir。它通过 OS 文件句柄解析真实路径,防住符号链接与 Windows junction 绕过。

内容提取 ​

控制从 HTML 中提取哪些内容。

字段默认值说明
ExtractArticletrue智能文章识别(自动定位主体内容)
ExtractMetadatatrue结构化元数据:解析作者、发布时间、摘要、站点名与规范链接,并让元数据标题优先
PreserveImagestrue保留图片信息
PreserveLinkstrue保留链接信息
PreserveVideostrue提取视频
PreserveAudiostrue提取音频

关闭不需要的媒体类型可以减少处理量:

go
cfg := html.DefaultConfig()
cfg.PreserveVideos = false
cfg.PreserveAudios = false
// 只提取文本、图片和链接

关闭 ExtractMetadata 的影响

它同时改变标题来源:Result.Title 不再取 JSON-LD headline 或 og:title,回退到 <title> → 正文 h1 → 文档首个 h1 → 首个 h2 的 DOM 顺序。Author、PublishedTime、Description、SiteName、CanonicalURL 五个字段保持空值。

输出格式 ​

控制文本输出中图片与链接的呈现方式。详见 输出格式实战。

字段默认值可选值
InlineImageFormat"none""none", "markdown", "html", "placeholder"
InlineLinkFormat"none""none", "markdown", "html"
TableFormat"markdown""markdown", "html"
Encoding""(自动)"utf-8", "gbk", "shift_jis", "windows-1252" 等

三个格式字段的取值可直接使用导出常量,避免拼写错误:html.FormatNone("none")、html.FormatMarkdown("markdown")、html.FormatHTML("html")、html.FormatPlaceholder("placeholder",仅 InlineImageFormat 接受)。常量值与字符串字面量等效,校验规则相同(大小写不敏感);常量清单见 API 参考:常量与错误。

go
cfg := html.DefaultConfig()
cfg.InlineImageFormat = html.FormatMarkdown
cfg.InlineLinkFormat = html.FormatHTML

Encoding 留空时走自动检测。已知编码时手动指定可跳过检测步骤,但仅在确知编码时使用——指定错误会得到乱码或 encoding detection failed 错误。详见 编码检测实战。

链接提取 ​

以下字段在 ExtractAllLinks 与阅读模式(ReadPage 系列)中生效。详见 链接提取实战。

字段默认值说明
ResolveRelativeURLstrue将相对 URL 解析为绝对 URL
BaseURL""解析基准;空时自动从 HTML 检测
IncludeImagestrue包含 <img> 链接
IncludeVideostrue包含 <video> 与 <iframe>/<embed>/<object> 嵌入链接
IncludeAudiostrue包含 <audio> 链接
IncludeCSStrue包含 <link rel="stylesheet">
IncludeJStrue包含 <script src>
IncludeContentLinkstrue包含相对 href 的 <a> 链接
IncludeExternalLinkstrue包含绝对或协议相对的 <a> 链接
IncludeIconstrue包含 favicon/icon

链接提取与内容提取互不影响

Include* 字段只作用于 ExtractAllLinks。内容提取(Extract)中的链接保留由 PreserveLinks 控制。

扩展 ​

字段说明
Scorer自定义内容评分器;nil 时使用内置默认评分器(内部实现)

自定义 Scorer 可针对特定站点优化文章识别。详见 测试与自定义扩展。

常见配置组合 ​

Web 爬虫 ​

批量抓取场景提高并发、缩短超时:

go
package main

import (
	"log"
	"time"

	"github.com/cybergodev/html"
)

func main() {
	cfg := html.DefaultConfig()
	cfg.WorkerPoolSize = 8                   // 提高批量并发
	cfg.ProcessingTimeout = 10 * time.Second // 缩短超时
	cfg.PreserveVideos = false               // 爬虫不需要视频
	cfg.PreserveAudios = false

	processor, err := html.New(cfg)
	if err != nil {
		log.Fatal(err)
	}
	defer processor.Close()

	// 批量提取
	pages := [][]byte{[]byte("<html><body>页面 1</body></html>")}
	batch := processor.ExtractBatch(pages)
	log.Printf("成功 %d, 失败 %d", batch.Success, batch.Failed)
}

API 后端服务 ​

处理用户提交的 HTML,用高安全配置并限制文件目录:

go
package main

import (
	"log"

	"github.com/cybergodev/html"
)

func main() {
	cfg := html.HighSecurityConfig()
	cfg.AllowedBaseDir = "/var/www/uploads" // 限制文件目录

	processor, err := html.New(cfg)
	if err != nil {
		log.Fatal(err)
	}
	defer processor.Close()

	// 处理用户上传的 HTML 文件
	result, err := processor.ExtractFromFile("/var/www/uploads/user.html")
	if err != nil {
		log.Fatal(err)
	}
	log.Println(result.Title)
}

内容迁移工具 ​

把旧站 HTML 转为 Markdown:

go
package main

import (
	"fmt"
	"log"

	"github.com/cybergodev/html"
)

func main() {
	processor, err := html.New() // DefaultConfig
	if err != nil {
		log.Fatal(err)
	}
	defer processor.Close()

	data := []byte(`<html><body><article><h1>旧文章</h1><a href="/post/123">链接</a></article></body></html>`)
	md, err := processor.ExtractToMarkdown(data)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(md)
}

ExtractToMarkdown 固定使用 markdown 格式,与 InlineImageFormat/InlineLinkFormat 无关,因此这里不需要 MarkdownConfig()。BaseURL 与 ResolveRelativeURLs 作用于 ExtractAllLinks 与阅读模式,不会改写 Extract 结果中的链接。

Validate ​

传入 html.New() 的配置会自动校验,也可以先手动调用 Validate():

go
cfg := html.DefaultConfig()
cfg.MaxInputSize = -1 // 故意设错
if err := cfg.Validate(); err != nil {
    log.Fatal(err) // html: invalid config: MaxInputSize=-1, must be positive
}

校验覆盖字段范围与格式字符串。无效配置返回 *ConfigError,可用 errors.Is(err, html.ErrInvalidConfig) 判断。完整约束见 API 参考 — 配置。

下一步 ​