This is an automated email from the ASF dual-hosted git repository.
kayx23 pushed a commit to branch release/3.17
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/release/3.17 by this push:
new 0e783c9c8 docs: correct global plugin execution order (#13858)
0e783c9c8 is described below
commit 0e783c9c8e7940d3ecdbe3e983b2ca58583edec9
Author: Traky Deng <[email protected]>
AuthorDate: Wed Aug 26 15:34:15 2026 +0800
docs: correct global plugin execution order (#13858)
---
docs/en/latest/terminology/global-rule.md | 2 +-
docs/en/latest/terminology/plugin.md | 15 +++++++--------
docs/zh/latest/terminology/global-rule.md | 2 +-
docs/zh/latest/terminology/plugin.md | 15 +++++++--------
4 files changed, 16 insertions(+), 18 deletions(-)
diff --git a/docs/en/latest/terminology/global-rule.md
b/docs/en/latest/terminology/global-rule.md
index 1007f4b05..a42403fdf 100644
--- a/docs/en/latest/terminology/global-rule.md
+++ b/docs/en/latest/terminology/global-rule.md
@@ -30,7 +30,7 @@ description: This article describes how to use global rules.
A [Plugin](./plugin.md) configuration can be bound directly to a
[Route](./route.md), a [Service](./service.md) or a [Consumer](./consumer.md).
But what if we want a Plugin to work on all requests? This is where we register
a global Plugin with Global Rule.
-Compared with the plugin configuration in Route, Service, Plugin Config, and
Consumer, the plugin in the Global Rules is always executed first.
+A global-rule plugin runs before a locally bound plugin in the same phase.
However, locally bound `rewrite` handlers run before global-rule `access`
handlers. See [Plugins execution order](./plugin.md#plugins-execution-order)
for the complete order.
## Example
diff --git a/docs/en/latest/terminology/plugin.md
b/docs/en/latest/terminology/plugin.md
index 0aee6fc13..f3d35a117 100644
--- a/docs/en/latest/terminology/plugin.md
+++ b/docs/en/latest/terminology/plugin.md
@@ -95,17 +95,16 @@ When a request goes through APISIX, the plugin's
corresponding methods are execu
## Plugins execution order
-In general, plugins are executed in the following order:
+Global and locally bound plugins for a matched HTTP Route are interleaved by
phase:
-1. Plugins in [global rules](./global-rule.md)
- 1. plugins in rewrite phase
- 2. plugins in access phase
+1. global-rule plugins in the `rewrite` phase;
+2. locally bound plugins in the `rewrite` phase;
+3. global-rule plugins in the `access` phase; and
+4. locally bound plugins in the `access` phase.
-2. Plugins bound to other objects
- 1. plugins in rewrite phase
- 2. plugins in access phase
+A locally bound `rewrite` handler runs before every global-rule `access`
handler. If a `rewrite` handler terminates the request, the `access` handlers
scheduled after it do not run, but `log` handlers still run.
-Within each phase, you can optionally define a new priority number in the
`_meta.priority` field of the plugin, which takes precedence over the default
plugins priority during execution. Plugins with higher priority numbers are
executed first.
+Within each of these groups, you can optionally define a new priority number
in the `_meta.priority` field of the plugin, which takes precedence over the
default plugin priority during execution. Plugins with higher priority numbers
are executed first. A priority does not move a plugin across phase or
global/local groups.
For example, if you want to have `limit-count` (priority 1002) run before
`ip-restriction` (priority 3000) when requests hit a route, you can do so by
passing a higher priority number to `_meta.priority` field of `limit-count`:
diff --git a/docs/zh/latest/terminology/global-rule.md
b/docs/zh/latest/terminology/global-rule.md
index 8b3dc7ad4..b2df11d54 100644
--- a/docs/zh/latest/terminology/global-rule.md
+++ b/docs/zh/latest/terminology/global-rule.md
@@ -33,7 +33,7 @@ description: 本文介绍了全局规则的概念以及如何启用全局规则
如果你需要一个能作用于所有请求的 Plugin，可以通过 Global Rules 启用一个全局的插件配置。
-全局规则相对于 Route、Service、Plugin Config、Consumer 中的插件配置，Global Rules 中的插件总是优先执行。
+同一阶段内的全局规则插件会先于局部绑定的插件执行。但是，局部绑定插件的 `rewrite` 处理函数会先于全局规则插件的 `access`
处理函数执行。完整顺序请参见[插件执行顺序](./plugin.md#插件执行顺序)。
## 使用示例
diff --git a/docs/zh/latest/terminology/plugin.md
b/docs/zh/latest/terminology/plugin.md
index 263998ff9..5656c9fc6 100644
--- a/docs/zh/latest/terminology/plugin.md
+++ b/docs/zh/latest/terminology/plugin.md
@@ -94,17 +94,16 @@ plugins:
## 插件执行顺序
-通常情况下，插件按照以下顺序执行：
+对于匹配 HTTP Route 的请求，全局规则插件和局部绑定的插件会按阶段交错执行：
-1. [全局规则](./global-rule.md) 插件
- 1. rewrite 阶段的插件
- 2. access 阶段的插件
+1. 全局规则插件的 `rewrite` 阶段；
+2. 局部绑定插件的 `rewrite` 阶段；
+3. 全局规则插件的 `access` 阶段；
+4. 局部绑定插件的 `access` 阶段。
-2. 绑定到其他对象的插件
- 1. rewrite 阶段的插件
- 2. access 阶段的插件
+局部绑定插件的 `rewrite` 处理函数会先于所有全局规则插件的 `access` 处理函数执行。如果某个 `rewrite`
处理函数终止了请求，则排在它之后的 `access` 处理函数不会执行，但 `log` 处理函数仍会执行。
-在每个阶段内，你可以在插件的 `_meta.priority`
字段中可选地定义一个新的优先级数，该优先级数优先于默认插件优先级在执行期间。具有更高优先级数的插件首先执行。
+在上述每个分组内，你可以在插件的 `_meta.priority`
字段中定义新的优先级数，该优先级会在执行时覆盖插件的默认优先级。优先级数越高，插件越先执行。优先级不会使插件跨越阶段或全局、局部分组执行。
例如，如果你想在请求到达路由时，让 `limit-count`（优先级 1002）先于 `ip-restriction`（优先级
3000）运行，可以通过将更高的优先级数传递给 `limit-count` 的 `_meta.priority` 字段来实现：
