配置重定向和重写

Orbit 拥有一个内置的重定向和重写引擎，在向您的项目请求任何内容之前运行，可以在 KPanel 中或作为存储库中的文件进行配置。本指南涵盖了两种方式、模式语法及其捕获、规则顺序、限制以及容易引起困惑的行为。

配置规则的位置

有两个地方，它们按固定顺序进行评估。

1. 在 KPanel 中。 在 Orbit 中打开您的项目，转到 Settings，然后向下滚动到该环境的 redirects and rewrites 部分。每个环境都有自己独立的一组规则，因此生产环境和预发布环境需要分别配置。
2. 在您的存储库中，作为 kaps.json 文件。下文将进一步介绍此内容。

面板规则首先进行评估。如果没有规则匹配，则尝试 kaps.json 规则。

在 KPanel 中添加规则

1. 点击 Add rule。
2. 填写 source，即与传入请求匹配的路径模式。占位符显示它期望的两种形式：/old-path or /blog/:slug。
3. 填写 destination。占位符显示 /new-path or https://...，因此本地路径和完整的外部 URL 都有效。
4. 选择规则类型：
   • 301 Permanent：URL 已永久移动。浏览器和搜索引擎会缓存此项。
   • 302 Temporary：暂时移动，不会缓存。用于活动和实验。
   • Rewrite：提供目标路径，而不更改浏览器地址栏中的 URL。
5. 点击 Save rules。

源路径模式

:id 和 :rest* 之间的区别是重要的。命名参数匹配 single segment，在下一个斜杠处停止。splat 匹配 everything remaining，包括斜杠。

在目标中使用捕获

按名称引用命名参数，将裸通配符引用为 *：

规则顺序

规则从列表顶部向下测试，first match wins。一旦规则匹配，就不考虑后面的规则。面板在列表下方显示："Rules are tested in order. First match wins."

如果没有规则匹配，请求将正常提供。

常见用例

重命名页面

您将 /about-us 重命名为 /about，并希望旧链接继续工作。

• 源：/about-us
• 目标：/about
• 类型：301 Permanent

移动整个部分

您的博客从 /news/:slug 移动到 /blog/:slug。

• 源：/news/:slug
• 目标：/blog/:slug
• 类型：301 Permanent

静默代理 API 路径

您想要 /api/v1/* 从不同的内部路径提供，而不暴露此更改。

• 源：/api/v1/:path*
• 目标：/api/internal/:path*
• 类型：Rewrite

临时占位符页面

• 源：/checkout
• 目标：/maintenance
• 类型：302 Temporary

将流量发送到另一个域

目标可能是绝对 URL，因此规则可以指向完全不同的站点。

• 源：/shop/:rest*
• 目标：https://shop.example.com/:rest*
• 类型：301 Permanent

使用 kaps.json 作为代码的配置

规则可以存在于您的存储库中而不是面板中。添加 kaps.json 文件，并确保您的构建将其复制到 output directory，因为 Orbit 从构建工件的根目录而不是存储库根目录读取它。

{
  "redirects": [
    { "source": "/about-us", "destination": "/about", "permanent": true },
    { "source": "/news/:slug", "destination": "/blog/:slug", "permanent": true },
    { "source": "/promo", "destination": "/spring-sale", "permanent": false }
  ],
  "rewrites": [
    { "source": "/api/v1/:path*", "destination": "/api/internal/:path*" }
  ],
  "headers": [
    {
      "source": "/*",
      "headers": [
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "X-Content-Type-Options", "value": "nosniff" }
      ]
    }
  ]
}

permanent: true 产生 301，permanent: false 产生 302。省略它会产生 301。

限制

• 每个环境最多 100 条重定向和重写规则，kaps.json 中最多 100 条。
• 每个环境最多 200 条自定义头规则。

超过限制的规则会被静默删除，而不会引发错误，因此请远远低于限制。

自定义响应头

除了重定向外，每个环境在 Settings 中都有一个响应头部分，用于在匹配的路径上注入 HTTP 头。它使用相同的路径模式语法，并为 HSTS、CSP、no-embed、no-sniff、referrer policy 和 CORS 提供快速添加预设。

与重定向不同，all 匹配的头规则都会应用，而不仅仅是第一条，当后面的规则设置相同的头时，它会覆盖前面的规则。Content-Length、Transfer-Encoding 和 Connection 被阻止，因为设置它们会破坏响应。

在依赖前值得了解的行为

• 规则仅匹配路径。 Fragment（#section）根本不会到达服务器；浏览器在重定向后会重新附加它们。
• 重写到不存在的路径会产生 404，而不是静默回退到原始路径。重写目标必须存在于您的构建输出中。
• 规则在向您的项目请求任何内容之前运行，因此它们适用于静态文件和服务器模式请求。
• 每个环境是独立的。 生产环境上的规则不适用于预发布环境或预览。有目的地复制它们。

删除规则

点击规则行上的垃圾图标，然后点击 Save rules 以应用更改。与添加一条规则一样，更改从下一次部署生效。

何时使用边缘函数

重定向引擎处理路径到路径的规则。当您需要规则引擎无法表达的逻辑时，请使用 edge function：基于头或 cookie 的分支、保留或重写查询参数、加权 A/B 路由或任何条件逻辑。

相关阅读

• Edge Functions
• 向您的项目添加自定义域
• 部署您的项目