AI Skills
oauth

oauth

热门

配置 OAuth 服务商（Google、Apple、Microsoft、Facebook、GitHub 等）以适配 portless 本地开发 URL。适用于设置 OAuth 重定向 URI、修复“redirect_uri_mismatch”或“invalid redirect”错误、为本地开发配置登录服务商，或当服务商拒绝 .localhost 子域名时。触发词包括“OAuth not working with portless”、“redirect URI mismatch”、“Google/Apple/Microsoft sign-in fails locally”、“configure OAuth for local dev”，或任何涉及 portless 域名的 OAuth 回调 URL 相关任务。

1万Star
334Fork
更新于 2026/7/30
获取 Skill源代码

相关 Skills

network-config-validation24万agent-security-manager7.2万release-openspec6.8万
SKILL.md
只读
名称
oauth
描述

配置 OAuth 服务商（Google、Apple、Microsoft、Facebook、GitHub 等）以适配 portless 本地开发 URL。适用于设置 OAuth 重定向 URI、修复“redirect_uri_mismatch”或“invalid redirect”错误、为本地开发配置登录服务商，或当服务商拒绝 .localhost 子域名时。触发词包括“OAuth not working with portless”、“redirect URI mismatch”、“Google/Apple/Microsoft sign-in fails locally”、“configure OAuth for local dev”，或任何涉及 portless 域名的 OAuth 回调 URL 相关任务。

在 Portless 中使用 OAuth

OAuth 服务商会根据域名规则校验重定向 URI。大多数服务商都会拒绝 .localhost 子域名，因为它们不在公共后缀列表（Public Suffix List）中，或者被明确禁止。Portless 通过 --tld 参数在真实有效的域名上运行应用，从而解决这一问题。

问题所在

当 portless 使用默认的 .localhost 顶级域（TLD）时，OAuth 服务商会拒绝形如 http://myapp.localhost:1355/callback 的重定向 URI：

服务商 localhost .localhost 子域名 拒绝原因
Google 允许 拒绝 未包含在其内置的 PSL 中
Apple 拒绝 拒绝 完全不支持 localhost
Microsoft 允许 允许 对 localhost 限制宽松
Facebook 允许 视情况而定 必须精准注册每一个 URI
GitHub 允许 允许 限制宽松

Google 和 Apple 的校验最为严格。Microsoft 和 GitHub 对 localhost 则相对宽松。

解决方案

使用有效的顶级域（TLD），使重定向 URI 能顺利通过服务商的校验：

portless proxy start --tld dev
portless myapp next dev
# -> https://myapp.dev

公共后缀列表（Public Suffix List）中的任何 TLD 都可以使用，例如 .dev、.app、.com、.io 等。

使用自持域名

直接使用 .dev 这类纯 TLD 意味着 myapp.dev 可能会与互联网上的真实域名冲突。建议在你控制的域名下使用多段 TLD，这样既能保持应用名称整洁，又能将域名结构保留在 TLD 中：

portless proxy start --tld local.yourcompany.dev
portless myapp next dev
# -> https://myapp.local.yourcompany.dev

这能确保出站流量绝不会解析到你不拥有的外部地址。对于团队开发，建议配置泛域名 DNS 解析记录（*.local.yourcompany.dev -> 127.0.0.1），这样每位开发者无需修改 /etc/hosts 即可实现本地域名解析，并且可以在服务商控制台中共享同一套重定向 URI 配置。

服务商配置

Google

  1. 前往 Google Cloud Console > Credentials
  2. 创建或编辑一个 OAuth 2.0 客户端 ID（Web 应用）
  3. 在已授权的 JavaScript 来源（Authorized JavaScript origins）中添加 portless 域名：https://myapp.dev
  4. 在已授权的重定向 URI（Authorized redirect URIs）中添加回调地址：https://myapp.dev/api/auth/callback/google

Google 会根据公共后缀列表校验域名。域名必须以受支持的 TLD 结尾。.localhost 子域名无法通过此校验，而 .dev、.app、.com 等均可顺利通过。

由于 .dev 和 .app 默认预装了 HSTS，必须使用 HTTPS。Portless 可通过 --https 自动处理 HTTPS 配置。

Apple

Apple Sign In 完全不支持 localhost 或 IP 地址。

  1. 前往 Apple Developer > Certificates, Identifiers & Profiles
  2. 注册一个 Services ID
  3. 配置 Sign In with Apple，将 portless 域名添加为 Return URL：https://myapp.dev/api/auth/callback/apple

该域名必须是可以在公网上解析的真实域名。由于 portless 在本地将域名映射到 127.0.0.1，浏览器虽然能正常访问，但 Apple 的服务端校验可能要求该域名在公网也能解析。如果 Apple 拒绝了该域名，请在公网 DNS 中为你的开发子域名添加一条指向 127.0.0.1 的 A 记录。

Microsoft (Entra / Azure AD)

  1. 前往 Azure Portal > 应用注册
  2. 创建或编辑应用注册
  3. 在身份验证（Authentication）下，添加 Web 重定向 URI：https://myapp.dev/api/auth/callback/azure-ad

Microsoft 允许在开发环境中使用任意端口的 http://localhost，并且大多数情况下也接受 .localhost 子域名。不过仍建议使用 portless 配置自定义 TLD，以保持各大服务商之间配置一致。

Facebook (Meta)

  1. 前往 Meta for Developers > 应用面板
  2. 在 Facebook 登录 > 设置中，将 portless URL 添加到有效的 OAuth 重定向 URI：https://myapp.dev/api/auth/callback/facebook

Facebook 要求精准注册每一个重定向 URI（不支持通配符）。默认启用的严格模式（Strict Mode）会强制进行完全匹配。

GitHub

  1. 前往 GitHub Developer Settings > OAuth Apps
  2. 设置 Authorization callback URL：https://myapp.dev/api/auth/callback/github

GitHub 对 localhost 和子域名的限制较松。虽然非强制要求使用自定义 TLD，但这样配置能保持开发环境统一。

身份验证库配置

NextAuth / Auth.js

设置 NEXTAUTH_URL 与 portless 域名一致：

NEXTAUTH_URL=https://myapp.dev

NextAuth 会以此构建回调 URL。如果不设置，回调可能会使用 localhost，从而导致不匹配错误。

Passport.js

在每个策略（Strategy）中设置 callbackURL 以使用 portless 域名：

new GoogleStrategy({
  clientID: process.env.GOOGLE_CLIENT_ID,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET,
  callbackURL: process.env.BASE_URL + "/auth/google/callback",
});

在环境变量中设置 BASE_URL=https://myapp.dev。

通用 / 手动配置

读取 portless 自动注入到子进程中的 PORTLESS_URL 环境变量：

const baseUrl = process.env.PORTLESS_URL || "http://localhost:3000";
const callbackUrl = `${baseUrl}/auth/callback`;

常见问题与排错

"redirect_uri_mismatch" 或 "invalid redirect URI"

OAuth 流程中发送的重定向 URI 与服务商处注册的不一致。请检查：

  1. 服务商侧注册的重定向 URI 是否与 portless 域名完全一致（包括协议、域名和路径）
  2. NEXTAUTH_URL 或类似变量是否已设置为 portless URL（而非 localhost）
  3. 代理服务运行使用的 TLD 是否正确（运行 portless list 进行确认）

服务商要求使用 HTTPS

.dev 和 .app TLD 默认预装了 HSTS，因此浏览器会强制要求 HTTPS。启动代理：

portless proxy start --tld dev

Portless 默认会在 443 端口启用 HTTPS（会自动通过 sudo 提升权限）。运行 portless trust 将本地 CA 添加到系统受信任的证书存储中，即可消除浏览器警告。

Apple 拒绝该域名

Apple 可能要求域名在公网上可解析。请为你的开发子域名添加一条指向 127.0.0.1 的 DNS A 记录：

myapp.local.yourcompany.dev  A  127.0.0.1

或者使用泛域名解析：*.local.yourcompany.dev A 127.0.0.1。

登录后回调跳转到了错误的 URL

身份验证库在构建回调 URL 时使用的是 localhost 而非 portless 域名。请设置相应的环境变量：

  • NextAuth：NEXTAUTH_URL=https://myapp.dev
  • Auth.js v5：AUTH_URL=https://myapp.dev
  • 手动配置：PORTLESS_URL 会被自动注入，用作基础 URL（base URL）即可

示例

参阅 examples/google-oauth 获取使用 Next.js + NextAuth + Google OAuth（配合 --tld dev）的完整示例。