ES 5.0 正式把脚本默认语言从 Groovy 切换为 Painless，两者语法看着很接近，但最容易踩坑、也是最普遍的差异就是：Groovy 里 params 下的参数可以直接写变量名使用，Painless 不再自动把参数注入到脚本作用域，所有外部传入参数都必须带上params.前缀访问，否则直接报变量未定义错误；这次切换的核心目的是安全隔离，Painless 是 ES 专门自研的白名单安全脚本引擎，用来解决 Groovy 远程执行带来的高危漏洞，除了参数写法，还有脚本结构、旧脚本配置项、script_file/script_id 等 API 同步废弃，很多老集群升级到 5.0 之后，脚本查询、更新、算分直接报错，大多都是这个原因。
Groovy 与 Painless 参数写法对照
Groovy（ES2.x/1.x）
"script": {
"lang": "groovy",
"inline": "doc['score'].value rate",
"params": {
"rate": 2
}
}
Painless（ES5.0+）✅
"script": {
"lang": "painless",
"source": "doc['score'].value params.rate",
"params": {
"rate": 2
}
}
ES5.0 脚本迁移重点变更清单
- 参数访问规则变更（最高频坑点）
- 脚本字段名称变更
- 废弃配置项
- 脚本文件、存储脚本 API 改名
- 安全限制收紧
- 内置上下文变量保留
Groovy：params 内的 key 自动注入，直接写rate；
Painless：必须显式params.rate或者params['rate']，不会自动注入变量。
旧inline字段改为source；不再支持简单字符串简写"script":"xxx"，必须写成 script 对象结构。
script.default_lang配置项直接删除，不再支持全局默认 Groovy。
script_file → file；script_id相关旧写法废弃，统一使用存储脚本 id 方式。
Painless 采用严格白名单，很多 Groovy 里可以调用的 Java 类、反射、动态方法全部禁用，防止注入攻击。
doc['字段名']、_score、ctx（更新脚本）这类内置上下文变量不用加 params 前缀，写法不变。
完整迁移步骤
- 遍历所有脚本，查找所有 params 传入的变量，全部补充params.前缀；
- 脚本结构改造：把字符串形式脚本，改成script {source,lang,params}对象格式；
- 移除配置里的script.default_lang；
- 替换 script_file、script_id 等废弃参数；
- 上线前小流量验证，重点捕获undefined variable报错；
- 脚本逻辑中如果调用了复杂 Java 方法，需要删减、替换为 Painless 支持的 API。
变更对比表
| 项目 | Groovy（ES 旧版本） | Painless（ES5.0+） |
|---|---|---|
| 参数访问 | 直接写变量名，自动注入 | 必须 params.xxx 显式访问 |
| 脚本主体 key | inline | source |
| 安全模型 | Java 类可大量调用，风险高 | 严格白名单，禁用反射、高危类 |
| 默认状态 | ES5 不再默认启用 | ES5 起默认脚本语言 |
| 变量冲突风险 | 高，参数和局部变量容易重名 | 低，参数来源明确，区分 doc/params/ctx |
【相关 FAQ】
问题 1：考古｜Groovy 迁 Painless，ES5.0 最常见的差异是参数要加 params. 前缀，是不是所有变量都要加 params.？
回答 1：不是，考古｜Groovy 迁 Painless，ES5.0 最常见的差异是参数要加 params. 前缀，只有外部 params 传入的自定义参数需要加 params.，doc 字段、_score、ctx 这类内置上下文变量不需要。
问题 2：考古｜Groovy 迁 Painless，ES5.0 最常见的差异是参数要加 params. 前缀，不改这个前缀会报什么错？
回答 2：考古｜Groovy 迁 Painless，ES5.0 最常见的差异是参数要加 params. 前缀，不加前缀运行脚本会直接抛出未定义变量异常，提示找不到对应变量。
问题 3：考古｜Groovy 迁 Painless，ES5.0 最常见的差异是参数要加 params. 前缀，ES5 还能不能继续使用 Groovy 脚本？
回答 3：考古｜Groovy 迁 Painless，ES5.0 最常见的差异是参数要加 params. 前缀，ES5 依然可以手动指定lang:groovy使用 Groovy，但官方标记废弃，需要额外开启，安全风险很高，不推荐。
问题 4：考古｜Groovy 迁 Painless，ES5.0 最常见的差异是参数要加 params. 前缀，Painless 用 params ['rate'] 和 params.rate 两种写法都可以吗？
回答 4：考古｜Groovy 迁 Painless，ES5.0 最常见的差异是参数要加 params. 前缀，两种写法都支持，params.rate更简洁，key 带特殊字符时适合params['rate']。
问题 5：考古｜Groovy 迁 Painless，ES5.0 最常见的差异是参数要加 params. 前缀，升级 ES5 只改参数前缀就够了吗？
回答 5：不够，考古｜Groovy 迁 Painless，ES5.0 最常见的差异是参数要加 params. 前缀，除了参数，还要改 inline→source、废弃 script_file 配置、清理 default_lang，同时检查 Groovy 里的反射、Java 调用代码。
【参考资料】
[2026-11-06]（考古｜Groovy 迁 Painless，ES 5.0 最常见的差异是参数要加 params. 前缀）腾讯云开发者社区
[2016-09-23]（Elasticsearch 5.0.0-beta1 released）Elastic 官方博客
[2016-09-21]（Painless: A New Scripting Language）Elastic 官方博客
[2026-11-06]（ES5 Painless 脚本迁移指南、报错排查）看云 ES 中文文档
【免责声明】
本文为 ES 5.0 脚本迁移考古资料整理，Groovy 迁移 Painless 的语法、API 变更以 Elasticsearch 官方版本文档为准；不同小版本（5.0~5.6）细节略有差异，线上脚本迁移前务必在测试环境验证，避免查询、更新业务异常。