如何将 PortPreview 与 Next.js 应用程序一起使用

要将 PortPreview 与 Next.js 应用结合使用，请在端口 3000 上运行 next dev，启动 npx portpreview 3000，然后使用 HTTPS URL 进行 OAuth 重定向、Webhook 路由处理程序、移动预览和共享正在进行的 UI — 无需部署。

为什么要对 Next.js 应用进行隧道传输

Next.js 通常是产品的公众形象：一个存储库中的营销页面、仪表板和 API 路由处理程序。第三方仍然无法达到localhost。当您在 next dev 或 next dev --turbo 中进行迭代时，隧道为您提供稳定的公共 HTTPS 源。

• Webhooks。 Stripe、Clerk 和重新发送 POST 到您的 app/api/... 路由。有关原始体模式，请参阅Next.js webhook local testing。
• OAuth。在开发过程中在 Auth0、Google 或 GitHub 中注册 https://your-tunnel.portpreview.dev/api/auth/callback/...。参见test OAuth callbacks locally。
• 移动设备和利益相关者预览。将隧道链接发送给质量检查或设计。参见share a local dev server。

快速启动

1. 来自您的 Next.js 项目：npm run dev（默认端口 3000）。
2. 在第二个终端中：npx portpreview 3000。
3. 在浏览器或手机中打开打印的 https://....portpreview.dev 网址。
4. 将外部服务指向同一来源以及您的 API 路径。

App Router API 在隧道后面路由

路由处理程序接收原始标头完好无损的代理请求 - 对于 Webhook 签名很有用。当提供商需要 Node 加密时，将 Webhook 路由保留在 Node 运行时上：

// app/api/health/route.ts
export async function GET() {
  return Response.json({ ok: true });
}

对于签名验证，请在解析 JSON 之前阅读await request.text()。全局读取正文的中间件将破坏 webhook；在 middleware.ts 匹配器中排除 /api/webhooks。

环境变量和公共 URL

当客户端代码必须知道其公共来源（OAuth、绝对资产 URL）时，请将活动隧道存储在 .env.local 中：

NEXT_PUBLIC_APP_URL=https://abc123.portpreview.dev

更改环境文件后重新启动next dev。对于仅限服务器的 Webhook 机密，请使用无前缀的变量，例如 STRIPE_WEBHOOK_SECRET。

WebSocket 和自定义服务器

如果您使用 socket.io 和 Next.js 运行自定义 Node 服务器，PortPreview 默认转发 WebSocket 升级。 Turbopack 不会改变隧道行为 - 只会改变捆绑器。

安全清单

• 请勿将 .env.local 或隧道 URL 提交至 git。
• 即使在隧道上也可以通过身份验证保护管理和预览路由。
• 广泛共享时轮换隧道会话。
• 回顾localhost tunnel security。

Next.js documentation 涵盖了路由处理程序和环境加载。 Start PortPreview free 用于 Next.js 友好的 HTTPS 隧道。