跳到主要内容

a6-plugin-redirect

概览​

redirect 插件会向客户端返回 HTTP 重定向响应（如 301、302 等）， 可将客户端重定向到新的 URI、强制使用 HTTPS，或使用正则表达式执行复杂的路径转换。与 proxy-rewrite（只会在转发到上游前重写请求）不同，该插件会直接向客户端返回重定向响应。

适用场景​

  • 通过将所有 HTTP 请求重定向到 HTTPS 来强制使用 HTTPS。
  • 将旧 URL 重定向到新地址（301 永久重定向）。
  • 使用正则捕获组进行基于模式的 URI 重写
  • 重定向到外部域名。
  • 在重定向期间追加或保留查询字符串。

插件配置参考（路由/服务）​

字段类型是否必填默认值说明
http_to_httpsboolean否false将 HTTP 重定向到 HTTPS，保留 URI 和查询字符串，并使用 301 状态码。
uristring否—目标重定向 URI。支持 Nginx 变量（$uri、$host 等），也可以是绝对 URL。
regex_uriarray[string]否—包含两个元素的数组：["regex_pattern", "replacement"]。PCRE 正则表达式支持捕获组。
ret_codeinteger否302重定向响应使用的 HTTP 状态码。
encode_uriboolean否false根据 RFC 3986 对 Location 请求头中的 URI 编码。
append_query_stringboolean否false将原始请求查询字符串追加到重定向 Location。

互斥关系：http_to_https、uri 和 regex_uri 一次只能配置其中一项。

注意：http_to_https 和 append_query_string 不能同时使用（http_to_https 已经会保留查询字符串）。

HTTPS 端口选择（用于 http_to_https）​

当 http_to_https 为 true 时，HTTPS 端口按以下优先级确定：

  1. plugin_attr.redirect.https_port 在 conf/config.yaml
  2. 如果配置了 SSL，则从 apisix.ssl.listen 中选择随机端口。
  3. 默认值：443

分步指南：在路由上启用 redirect​

1. HTTP 到 HTTPS 重定向​

在 APISIX 中启用 HTTPS 重定向：

a6 route create -f - <<'EOF'
{
  "id": "force-https",
  "uri": "/*",
  "plugins": {
    "redirect": {
      "http_to_https": true
    }
  }
}
EOF

结果：http://example.com/path?q=1 → https://example.com/path?q=1（301）

2. 简单 URI 重定向（永久移动）​

a6 route create -f - <<'EOF'
{
  "id": "old-to-new",
  "uri": "/old-page",
  "plugins": {
    "redirect": {
      "uri": "/new-page",
      "ret_code": 301
    }
  }
}
EOF

3. 使用捕获组进行正则重定向​

a6 route create -f - <<'EOF'
{
  "id": "regex-redirect",
  "uri": "/blog/*",
  "plugins": {
    "redirect": {
      "regex_uri": ["^/blog/(\\d{4})/(\\d{2})/(.*)$", "/articles/$1-$2-$3"],
      "ret_code": 301
    }
  }
}
EOF

结果：/blog/2024/03/my-post → /articles/2024-03-my-post

常见模式​

重定向到外部域名​

{
  "plugins": {
    "redirect": {
      "uri": "https://new-domain.com/api/v2",
      "ret_code": 301
    }
  }
}

使用 NGINX 变量重定向​

{
  "plugins": {
    "redirect": {
      "uri": "https://new-domain.com$request_uri",
      "ret_code": 301
    }
  }
}

保留完整的原始路径和查询字符串。

追加尾部斜杠​

{
  "plugins": {
    "redirect": {
      "uri": "$uri/",
      "ret_code": 301
    }
  }
}

保留查询字符串进行重定向​

{
  "plugins": {
    "redirect": {
      "uri": "/new-path",
      "append_query_string": true,
      "ret_code": 302
    }
  }
}

请求：/old-path?foo=bar&baz=1 → Location：/new-path?foo=bar&baz=1

对 URI 中的特殊字符编码​

{
  "plugins": {
    "redirect": {
      "uri": "/path with spaces/resource",
      "encode_uri": true,
      "ret_code": 302
    }
  }
}

Location 请求头：/path%20with%20spaces/resource

用于维护的临时重定向（302）​

{
  "plugins": {
    "redirect": {
      "uri": "/maintenance.html",
      "ret_code": 302
    }
  }
}

使用 302（临时重定向），避免浏览器缓存该重定向。

故障排查​

现象原因解决方法
重定向循环路由匹配了重定向目标确保目标 URI 不会匹配同一路由
HTTPS 端口错误默认端口选择不正确在 config.yaml 中设置 plugin_attr.redirect.https_port
查询字符串丢失使用 uri 时未设置 append_query_string添加 "append_query_string": true，或使用 $request_uri
查询字符串重复append_query_string 与 $request_uri 同时使用不要同时使用二者；$request_uri 已包含查询字符串
Nginx 变量为空变量不存在不存在的变量会解析为空字符串（不会报错）
正则表达式未匹配转义或模式有误在 JSON 中转义反斜杠：\\d+；使用 PCRE 语法测试正则表达式
同时设置多个重定向选项http_to_https、uri 和 regex_uri 互斥三个选项只能选择其中一个

配置同步示例​

version: "1"
routes:
  - id: force-https
    uri: /*
    plugins:
      redirect:
        http_to_https: true
  - id: old-blog-redirect
    uri: /blog/*
    plugins:
      redirect:
        regex_uri:
          - "^/blog/(\\d{4})/(\\d{2})/(.*)"
          - "/articles/$1-$2-$3"
        ret_code: 301

本文根据 api7/a6 仓库中的 a6-plugin-redirect/SKILL.md 生成。可在 AI Agent Skills 页面浏览全部 Skill。