> 9.0 起高亮的 `force_source` 参数不再支持。这个参数的作用原本是"强制从 `_source` 取内容做高亮"，是给那些没建 term vector 又想快速高亮的场景用的兜底。现在官方把它删了——请求里带这个参数会失败。

## **说明**

本文描述问题及解决方法同样适用于 [腾讯云 Elasticsearch Service（ES）](https://cloud.tencent.com/document/product/845)。

## 官方条目

9.0 的 changelog 标为 breaking（[9.0.0.yml 第 531–540 行 @ v9.4.2](https://github.com/elastic/elasticsearch/blob/v9.4.2/docs/release-notes/changelog-bundles/9.0.0.yml#L531-L540)），PR 116943，`area: Highlighting`。

内容很短，两句：

> details: The deprecated highlighting `force_source` parameter is no longer supported.
> impact: Users should remove usages of the `force_source` parameter from their search requests.

官方没解释这个参数原本是干什么的。所以下面关于它作用的部分，是根据高亮机制整理的背景，不是引自官方文档——这点在每处都标清楚了。

## 先说高亮的两种取值路径

要理解 `force_source`，得先知道 ES 做高亮时从哪里取文本。

高亮要标出"这段文本里哪个词命中了"，需要拿到原始文本。ES 有两条路：

一，从索引结构里取。 如果字段建了 `term_vector`（带 position/offset 信息），高亮器可以直接从索引里读出词的位置，速度快。

二，从 `_source` 里取。 读取原始文档，重新分析一遍找出命中位置。这条路不需要预先建 term vector，但每次都要重新分析文本，慢。

权衡很清楚：

* 建 `term_vector` → 占更多磁盘，但高亮快；
* 不建 → 省空间，但高亮要走 `_source` 重新分析，慢。

这个权衡是理解整件事的基础：高亮快不快，主要由索引时有没有存位置信息决定，而不是由查询时的参数决定。所以后面会说，参数开关的影响远小于 mapping 配置。

文档里能看到这个权衡的影子——`fvh` 高亮器那节明确要求 `term_vector` 设为 `with_positions_offsets`（[highlighting-settings.md 第 100 行 @ v9.4.2](https://github.com/elastic/elasticsearch/blob/v9.4.2/docs/reference/elasticsearch/rest-apis/highlighting-settings.md#L100)）：

> all `matched_fields` must have `term_vector` set to `with_positions_offsets`

## `force_source` 大概解决什么问题

按理解（官方文档没解释，这段是推断）：

`force_source` 的作用是显式指定"这次高亮就从 `_source` 取"。

什么时候需要显式指定？能想到的场景是：字段**同时具备**走索引的条件（比如建了 term vector），但你这一次想强制走 `_source`——可能是为了拿到更完整的高亮结果，或者为了和其它行为保持一致。

也就是说，它是个覆盖默认选择的开关，而不是"没 term vector 时的兜底"。

这一点要特别说明：不确定这个理解对不对。因为官方既没在 changelog 里解释，在 v9.4.2 的文档里也搜不到 `force_source` 的说明（搜不到本身印证了它已被移除，但也就拿不到官方定义）。

所以本篇关于参数作用的描述，可靠性低于其它篇的源码核实内容。 如果你需要确切知道它做什么，得去查 8.x 的文档或者 PR 116943 的讨论。

## 移除之后会怎样

按 impact 的说法，请求里带 `force_source` 会失败——要么报错，要么参数不再被识别。

具体是哪一种，官方没说。按同类"移除参数"的改动推测，ES 对未知参数的校验通常比较严格，多半是直接报错。但这点未实测。

对使用者来说，处置动作很清楚：从搜索请求里去掉这个参数。

```sh
# 找出代码里用到它的地方
grep -rn "force_source" --include=*.json --include=*.py --include=*.go --include=*.js .
```

这个 grep 很快，建议升级前跑一次——确认"没有"和"有"同样是有价值的结果，前者能让你放心跳过这条改动。

## 为什么影响面小

判断这条 breaking 的影响面在 9.0 里属于**很小**的一档，理由有三：

一，它已经被标记为 deprecated 一段时间了。 changelog 里 details 直接称它为 `deprecated highlighting force_source parameter`——也就是说在移除之前，用它就已经会收到弃用提示。注意看日志的团队早就改了。

二，它是个可选参数。 不用高亮的人完全无关；用高亮但不指定这个参数的，也无关。只有显式写了它的才受影响。

三，高亮通常配合 term vector 使用。 认真做高亮性能的场景，早就按官方建议建了 `term_vector`，不太需要这个"强制走 source"的开关。

三条加起来就是：用到它的人本来就少，而这些人里大部分在弃用提示出现后就改掉了。所以实际撞上的人应该不多——但仍建议 grep 一次确认，因为"应该不多"是推断，grep 是事实。

## 一个更该关心的高亮配置点

既然写到高亮，把那个真正影响性能的配置说一下——它比 `force_source` 重要得多：

字段上要不要建 `term_vector`。

按文档的说法，`fvh`（fast vector highlighter）要求 `term_vector` 设为 `with_positions_offsets`。而如果字段没建 term vector，高亮就得走"重新分析 `_source`"那条路。

判断是：如果高亮上遇到性能问题，先看 term_vector，而不是找什么参数开关。配置决定路径，参数只是在路径已定的情况下做微调。

这也是对这次改动的整体看法——`force_source` 是个微调开关，去掉它对整体高亮能力没有影响。真正该关心的是字段的索引配置。

## 高亮器类型的选择

顺着 term_vector 再说一层，因为这决定了你能用哪种高亮器。

ES 有几种高亮器，按文档提到的名字至少有这些（未找到完整的官方清单，以下是按文档出现过的整理）：

* `unified`——Lucene 的 UnifiedHighlighter，通用选择；
* `fvh`（fast vector highlighter）——要求字段建 `term_vector`，但高亮快；
* `plain`——基础高亮器，走重新分析的路子。

选择逻辑是这样的：

| 高亮器 | 对索引的要求 | 特点 |
|---|---|---|
| `fvh` | 必须 `term_vector: with_positions_offsets` | 快，但要额外存储 |
| `unified` / `plain` | 无特殊要求 | 慢一些，但不用改 mapping |

所以配置项是**连动的**：

1. 先决定用不用 `fvh`；
2. 用的话，字段必须配 `term_vector`；
3. 这会增加索引体积，但换来高亮速度。

这里的判断是：多数场景用默认高亮器就够了，不要为了性能盲目上 `fvh`。上它要改 mapping（对存量数据意味着重建），而且占更多磁盘。只有在高亮确实是瓶颈时才值得。

（说明：高亮器的完整清单和各自要求以你版本的官方文档为准，未逐项核实。上面是按 v9.4.2 文档里出现的内容整理的。）

## 这条改动属于哪一类

把它归为"参数清理"，和 [单数据节点水位线开关移除](./es9-103-watermark-single-data-node-removed.md) 写的 `enable_for_single_data_node`、以及 [Watcher 的 types 字段](./es9-86-watcher-search-types-removed.md) 写的 watcher `types` 是同一类。

三者的共同模式：

* 参数先被标记弃用；
* 在**主版本**被移除（这里是 9.0）；
* 官方 impact 都说"**去掉它**"（而不是"改成 X"）——说明没有替代项，功能直接消失。

最后这点值得留意：有替代项的和没替代项的是两类改动。

* 有替代项（如远程集群证书 → API key）→ 要做迁移工作；
* 没替代项（如本条）→ 只要删掉，行为回到默认路径。

判断属于哪类，看 impact 的措辞就能分辨——说"remove"的是后者，说"migrate/use instead"的是前者。

这个分辨在读 changelog 时很实用：同样是 breaking，前者是删一行配置，后者可能是一个季度的迁移项目。提前分清能避免排期误判。

## 怎么确认自己有没有用到

除了 grep 代码，还有一个更可靠的办法：看 8.x 集群上的弃用日志。

这个参数在移除前是 deprecated 状态，用过它应该会在弃用日志里留下记录：

```sh
grep -i "force_source" /var/log/elasticsearch/*_deprecation.log | head
```

能查到就说明确实在用（或者曾经用过）。查不到的话，多半不用管。

为什么建议两个办法都做：grep 代码只能找到自己代码里显式写的，找不到 SDK 或者看板里生成的。而弃用日志是服务端记录的实际发生过的调用——覆盖更全。

这个思路在前面几篇里反复用过（[单数据节点水位线开关移除](./es9-103-watermark-single-data-node-removed.md)、[REST API V7 兼容移除](./es9-105-rest-api-version-v7-removed.md) 都提到查弃用日志），因为它确实比翻代码可靠：日志反映的是真实行为，代码反映的是你认为的行为。

如果两者结果不一致——比如代码里没找到但日志里有——那说明有调用方不在你的代码库里，值得再找找（看板、第三方工具、定时任务都可能是来源）。

## 写在最后

这条 breaking 的技术内容极少——一个参数被移除，处置动作是把请求里那个参数删掉。

写它主要是想说清一件事：这类"参数清理"的条目，读的时候要分辨它有没有替代项。

本次的 `force_source` 属于没有替代项——删掉即可，行为回到默认的高亮路径。而有替代项的（比如 [远程集群证书认证弃用](./es9-106-remote-cluster-cert-model-deprecated.md) 写的远程集群证书模式）就要规划迁移，工作量完全不同。

一，升级前查两处：代码里 grep `force_source`，弃用日志里也 grep 一次。 前者找你写的，后者找实际发生过的——两者不一致时，说明有调用方不在你的代码库里。

二，高亮性能看 term_vector，不看参数开关。 字段的索引配置决定了高亮走哪条路，这才是大头。想上 `fvh` 要改 mapping，对存量数据意味着重建，别为了"可能更快"盲目做。

另外要坦白一点：本篇关于 `force_source` 具体作用的说明可靠性不如其它篇——官方没解释，也未能在 v9.4.2 文档里找到定义。是按高亮机制推断的，已在正文标注。如果你需要确切答案，去查 8.x 文档或 PR 116943 的讨论。

写这类"官方没解释"的条目时，原则是不编造细节、把推断标清楚。宁可让读者知道这一点不确定，也不要给一个看起来确定但没依据的说法——后者在排查时会误导人。

## 参考

- [changelog 9.0.0：Remove support for deprecated `force_source` highlighting parameter（第 531–540 行）@ v9.4.2](https://github.com/elastic/elasticsearch/blob/v9.4.2/docs/release-notes/changelog-bundles/9.0.0.yml#L531-L540)
- [breaking-changes.md 第 295 行：同一条目的汇总列表 @ v9.4.2](https://github.com/elastic/elasticsearch/blob/v9.4.2/docs/release-notes/breaking-changes.md#L295)
- [`highlighting-settings.md`：高亮相关配置（`fvh` 要求 term_vector）@ v9.4.2](https://github.com/elastic/elasticsearch/blob/v9.4.2/docs/reference/elasticsearch/rest-apis/highlighting-settings.md)
- [PR 116943](https://github.com/elastic/elasticsearch/pull/116943)

> 本文对照 Elasticsearch `v9.4.2` 标签的 changelog 与文档核对，changelog 引文逐字取自原文。**关于 `force_source` 参数具体作用的说明是推断**——官方 changelog 未解释，且 v9.4.2 文档中已无该参数条目（印证已移除），故无法核实，正文已明确标注。带该参数的请求是报错还是静默忽略，本文未实测。撰写时未启动集群、未运行测试。


9.0 起高亮的 force_source 参数不再支持。这个参数的作用原本是"强制从 _source 取内容做高亮"，是给那些没建 term vector 又想快速高亮的场景用的兜底。现在官方把它删了——请求里带这个参数会失败。

ES 的高亮参数 `force_source` 被移除了，请求里带了会报错

9.0 起高亮的 forcesource 参数不再支持。

官方产研

云计算

后端

大数据

Elasticsearch 9.0移除高亮force_source参数，请求中携带将失败。该参数用于强制从_source取内容高亮，影响面小：已弃用、可选、使用少。升级前建议grep代码及弃用日志确认使用情况。高亮性能关键在于term_vector配置而非参数开关。无替代项，直接删除参数即可。

Elasticsearch 

代码解释

JSON

2026上云采购 | AI焕新·智启新局

bigdata-class

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

ES 的高亮参数 `force_source` 被移除了，请求里带了会报错-腾讯云开发者社区-腾讯云

ES 的高亮参数 `force_source` 被移除了，请求里带了会报错

ES 的高亮参数 `force_source` 被移除了，请求里带了会报错

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐