在 Cloudflare Workers、Next.js 或 Caddy 上设置集成模式

本页说明如何在三种已提供现成开源集成的平台上，以 集成模式 连接域名。每个平台都通过规则文件提供你在 RedirHub 中管理的重定向、短链接和二维码链接，无需在每次变更后重新部署，并会将每次重定向记录到你的分析中。

开始前：rules 地址和密钥#

1. 在控制台中，将域名添加到 Hostnames 下，并选择 通过你自己的平台连接。
2. 选择你的平台。控制台会显示该域名的 rules 地址 和你的工作区的 集成密钥，以及一个已填入这两项内容的提示，你可以把它粘贴到 AI 编程代理（如 Claude、Cursor、ChatGPT 等）中，而无需手动执行下面的步骤。
3. 将密钥存储为机密或环境变量。rules 地址不是机密，但不要公开发布。

部署后，/_redirhub/check 上的首次响应会连接该域名。控制台每 15 分钟检查一次，或可通过 立即检查 立刻检查。

Cloudflare Workers#

位于源站前的 Worker 会提供重定向服务，并将其他所有请求继续转发。源代码和完整选项：redirhub/cloudflare-redirects。

bashnpm install @redirhub/cloudflare-redirects

创建 src/index.ts：

typescriptimport { createWorker } from '@redirhub/cloudflare-redirects'

interface Env {
  ACME_RULES_URL: string
  ACME_INTEGRATION_KEY: string
}

export default createWorker<Env>({
  settings: (env) => ({ rulesUrl: env.ACME_RULES_URL, key: env.ACME_INTEGRATION_KEY }),
})

在 wrangler.toml 中为主机名和规则地址设置路由（仪表板会显示你域名的确切变量名）：

tomlname = "shop-redirects"
main = "src/index.ts"
compatibility_date = "2026-11-01"
routes = [{ pattern = "shop.example.com/*", zone_name = "example.com" }]

[vars]
ACME_RULES_URL = "https://rules.example.com/…/TOKEN.txt"

将密钥作为 secret 添加并部署：

bashnpx wrangler secret put ACME_INTEGRATION_KEY
npx wrangler deploy

• 路由必须覆盖该主机名的每个路径，包括 /_redirhub/check。
• 通配规则可用：当你的源站返回 404 时，Worker 会改为重定向。
• 404 报告可用：当该主机名启用 报告 404 页面 时，会上报你源站的 404。

Next.js（Vercel 或自托管）#

重定向在你的代理中运行（Next.js 16）或中间件中运行（Next.js 15 及更早版本），在你的页面之前。源码和完整选项：redirhub/nextjs-redirects。

bashnpm install @redirhub/nextjs-redirects

将规则地址和密钥作为环境变量添加（Vercel 项目设置中，或本地的 .env.local 中）。切勿在密钥前加上 NEXT_PUBLIC_ 前缀。然后创建 proxy.ts（或者在 Next.js 15 及更早版本中使用 middleware.ts 并搭配 export function middleware）：

typescriptimport type { NextFetchEvent, NextRequest } from 'next/server'
import { createProxy } from '@redirhub/nextjs-redirects'

const redirects = createProxy({
  rulesUrl: process.env.ACME_RULES_URL,
  key: process.env.ACME_INTEGRATION_KEY,
})

export async function proxy(request: NextRequest, event: NextFetchEvent) {
  const answer = await redirects(request, event)
  if (answer) return answer
  // … 你自己的代理逻辑，或者什么都不做
}

• 先调用它，在重写和区域设置处理之前。
• 匹配器必须放行 /_redirhub/check 以及你要重定向通过的路径。一个跳过所有包含点的路径的匹配器，也会跳过诸如 /old.html 这样的规则。
• next.config 中的重定向会在代理之前运行，因此它们可能会遮蔽你的规则。
• 代理在页面之前运行，并且从不查看你的应用是否返回 404，因此通配规则和 404 报告不会在那里提供。若要同时添加这两者，请使用 createRedirects() 以及其 afterSite()，在这里你能看到最终结果，例如在路由处理程序中（见 README）。

Caddy#

适用于您自己的服务器的 Caddy v2 模块。一个 Caddy 可以通过一个工作区规则地址服务于您所有的集成域名，并且它只能针对规则中的主机名按需颁发 HTTPS 证书。源代码和完整选项：redirhub/caddy-redirects。

使用该模块构建 Caddy：

bashxcaddy build --with github.com/redirhub/caddy-redirects

对于 Caddy，请从集成密钥面板复制工作区规则地址，而不是按域名的地址。然后将处理程序添加到您的 Caddyfile：

text{
	on_demand_tls {
		permission redirects
	}
}

https:// {
	tls {
		on_demand
	}
	redirects {
		rules_url https://rules.rediredge.com/abc123/TOKEN.txt
		key {env.REDIRHUB_INTEGRATION_KEY}
	}
	reverse_proxy localhost:8080
}

• 在 Caddy 的环境中设置REDIRHUB_INTEGRATION_KEY，然后重新加载 Caddy。
• 更改会在一两秒内通过推送到达，轮询作为后备方案。最后有效的规则会保存在磁盘上，因此重启后会立即开始重定向。
• 当路由其余部分返回 404 时，兜底规则才会生效。在带有回退的try_files之后（单页应用），站点永远不会返回 404，所以兜底规则永远不会触发。
• 404 报告遵循每个主机名的报告 404 页面开关。使用report_404 all时，站点块的每个 404 都会被报告，即使是您尚未添加到 RedirHub 的主机名。

在您部署之后#

• 在“主机名”下打开该域名并点击立即检查。状态应变为“已连接”。
• 在隐私窗口中或使用curl -I测试规则。
• 如果域名仍停留在“等待中”或重定向未触发，请参阅集成模式故障排除。