常见原因是ts_vector与ts_query配置不匹配，如english与simple混用；需统一配置、检查不可见字符；自定义高亮须成对指定标签且无空格；plainto_tsquery对连字符处理不佳，建议改用websearch_to_tsquery；性能差因重复解析，宜用生成列+GIN索引优化。
为什么 ts_headline() 返回空字符串或原始文本
常见原因是文档和查询的 tsvector / tsquery 使用了不匹配的文本搜索配置（如 english vs simple）。ts_headline() 不会自动转换语言规则，它只在给定配置下匹配词干和停用词。比如用 to_tsvector('english', 'running') 生成向量，但用 to_tsquery('simple', 'run') 查询，就无法命中——因为 simple 不做词干化，且大小写敏感。
实操建议：
- 确保
ts_headline()的第三个参数（配置名）与构建tsvector和tsquery时一致，例如统一用'english' - 若字段未预建
tsvector列，直接在查询中调用to_tsvector('english', body)，别漏掉配置参数 - 检查目标字段是否含不可见字符（如零宽空格），
ts_headline()对非法 UTF-8 或控制字符可能静默失败
如何自定义高亮标记而不依赖默认的 <span>
ts_headline() 支持通过选项参数替换默认标签，但必须成对指定：起始标记和结束标记。它不接受单个标签，也不支持嵌套 HTML 属性（如 class="highlight"）——这些会被原样输出，不解析为 HTML 属性。
实操建议：
- 用
ts_headline(body, q, 'StartSel=<em> StopSel=</em>')替换默认的<span>，注意等号前后**不能有空格**，且引号需匹配外层 SQL 字符串 - 若需加 class，只能写成
StartSel=<em class="hl">，但双引号必须用"转义，否则 SQL 解析报错 - 避免使用
<b>等语义过强的标签；前端渲染时若已用 CSS 控制样式，纯文本标记（如[[[/]]]）反而更安全、易清洗
为什么 plainto_tsquery() 匹配不到带连字符的词（如 “e-mail”）
plainto_tsquery() 默认按空格和标点切分词元，但连字符在多数配置（如 english）中被视作分词符，导致 “e-mail” 被拆成 e 和 mail 两个独立词元。而原文本中的 to_tsvector() 可能保留了完整 token（取决于字典规则），造成查询与向量不一致。
实操建议：
- 改用
phraseto_tsquery()或websearch_to_tsquery()，后者对连字符更宽容，且支持自然语言语法（如引号短语） - 若必须用
plainto_tsquery()，先对用户输入做预处理：用正则将e-mail→"e-mail"，再传入函数 - 测试时用
SELECT to_tsvector('english', 'send e-mail now') @@ plainto_tsquery('english', 'e-mail');验证是否返回t，避免上线后才发现漏匹配
高亮性能差？别在 SELECT 中反复调用 to_tsvector()
每次调用 to_tsvector('english', body) 都触发全文解析、词干化、停用词过滤——对长文本或大结果集，CPU 开销显著。尤其当 body 字段未索引、且 WHERE 条件又靠 @@ 匹配时，数据库可能先全表扫描再高亮，双重低效。
实操建议：
- 为高频搜索字段添加生成列：
ALTER TABLE docs ADD COLUMN body_tsv tsvector GENERATED ALWAYS AS (to_tsvector('english', body)) STORED;，并在此列上建 GIN 索引 - 查询时用
WHERE body_tsv @@ q过滤，再用ts_headline(body, q, '...')高亮——避免重复解析同一字段 - 如果
body更新频繁，生成列自动维护，无需应用层干预；但注意STORED会占用额外磁盘空间
