用途:解决 Portless 默认 .localhost 子域被多数 OAuth 提供商拒绝重定向 URI 的问题。OAuth 提供商会校验重定向域名的合法性,而 .localhost 子域不在公共后缀列表(PSL)内或遭明确屏蔽。
主要能力:通过 --tld 参数把应用运行在真实有效域名上,使重定向 URI 通过校验。命令示例:portless proxy start --tld dev;portless myapp next dev,得到 https://myapp.dev。任何在公共后缀列表中的 TLD(.dev、.app、.com、.io 等)均可。官方建议使用自己掌控的多段 TLD,如 local.yourcompany.dev,避免与真实域名冲突;团队可设置通配 DNS(*.local.yourcompany.dev -> 127.0.0.1)。
各提供商要点:Google 需在 Cloud Console 凭据中填写授权的 JavaScript 来源与重定向 URI,域名必须以被认可的 TLD 结尾;Apple 完全不允许 localhost 或 IP,需在 Apple Developer 注册 Services ID 并添加 Return URL,域名通常还需可公开解析;Microsoft 对 localhost 较宽松,在 Azure 应用注册的 Authentication 中添加 Web 重定向 URI;Facebook 要求精确注册每个重定向 URI(不支持通配符,默认启用严格模式);GitHub 较为宽松,在 OAuth Apps 中设置 Authorization callback URL 即可。
认证库配置:NextAuth/Auth.js 设置 NEXTAUTH_URL(v5 用 AUTH_URL)匹配 portless 域名;Passport.js 在各策略中设置 callbackURL;通用场景读取 portless 注入的 PORTLESS_URL 环境变量作为 base URL。
限制与排错:.dev、.app 为 HSTS 预加载,强制 HTTPS,Portless 默认在 443 端口提供 HTTPS(自动 sudo 提权),可运行 portless trust 把本地 CA 加入系统信任库。出现 redirect_uri_mismatch 时检查注册 URI 是否与协议、主机、路径完全一致、环境变量是否指向 portless 而非 localhost、代理 TLD 是否正确(portless list 可验证);Apple 若拒绝域名,可添加指向 127.0.0.1 的公开 DNS A 记录。