portless 环境变量实战从稳定本地 URL 到手机直连与公网分享的调法【免费下载链接】portlessReplace port numbers with stable, named local URLs. For humans and agents.项目地址: https://gitcode.com/GitHub_Trending/por/portless本地开发时localhost 后面的端口号每次重启都变。portless 的本地代理让你直接访问https://myapp.localhost它的调优靠PORTLESS_*环境变量。端口号由 portless 在4000–4999区间随机分配之后一直替你管理你只需要记住名字。想先了解背景可以看 README本文不列清单而是按一条使用动线讲——本地跑起来 → 手机/局域网访问 → 对外分享 → 旁路与排障——每个变量放在它真正被用到的场景里。一条命令跑起来URL 稳定下来端口交给 portless 管跑portless myapp next dev时实际发生三件事portless 先起一个 HTTPS 反向代理默认占443纯 HTTP 时为80你的应用拿到4000–4999里一个随机端口通过注入的PORT环境变量知道该监听哪里之后https://myapp.localhost永远指向这个应用端口换了你也不用改任何东西。关键在这里所有显式PORTLESS_*环境变量优先于portless.json和上次运行记忆的默认值。本地场景最常动的六个变量如下完整定义见 配置文档变量它解决的痛点默认值PORTLESS_PORT443 需要 root 或被其他服务占着443HTTPS/80HTTPPORTLESS_HTTPSCI 或不信任本地 CA 时关掉 HTTPS开启PORTLESS_TLD本地域名结构和生产对不上localhostPORTLESS_WILDCARD想恢复未注册子域回退父路由严格匹配PORTLESS_SYNC_HOSTS自己管 hosts 文件或环境受限开启PORTLESS_APP_PORT外部工具已经指定了应用端口随机 4000–4999代理端口被占或不想要 sudoPORTLESS_PORT443 需要 root 权限开发机上还常被其他服务占着。给代理换个端口一行就行PORTLESS_PORT8443 portless proxy start执行后代理改在 8443 上监听你再也不用为抢 443 加 sudo写进~/.bashrc就长期生效。别踩这个坑非法值非数字、超出 1–65535会被静默忽略并回落到协议默认端口不会报错提醒你解析逻辑在 cli-utils 实现。让本地域名结构和生产一致PORTLESS_TLD想让本地 URL 长得像线上TLD 支持单个或多段域名逗号分隔PORTLESS_TLDlocalhost,dev.example.com portless执行后你会拿到dev.example.com后缀的 URL多个 TLD 重叠时按最长后缀优先匹配注入的PORTLESS_URL取第一个 TLD。变更历史见 CHANGELOG。⚠️ 别把PORTLESS_TLD写成.local——它和 mDNS/Bonjour 冲突.dev被 Google 持有且有 HSTS 风险。官方推荐 IANA 保留的.test。CI 里关掉 HTTPSPORTLESS_HTTPS0CI 机器通常没有本地 CA浏览器也不值得信任它。设PORTLESS_HTTPS0等价--no-tls代理切到 80 端口的纯 HTTP整条链路不再涉及证书。外部工具已经指定端口PORTLESS_APP_PORT 的优先级链有些工具链或团队约定已经给应用定好端口这时别让 portless 随机分PORTLESS_APP_PORT3100 portless myapp next dev启动后子进程会收到PORT3100应用监听这个固定端口而不是随机端口。应用端口的取值优先级高到低--app-port参数 PORTLESS_APP_PORTpackage.json的portless键 portless.json 自动分配规则见 配置文档。取值必须是 1–65535否则启动报错退出校验在 cli.ts。子域严格匹配与 /etc/hosts 同步的取舍默认是严格路由api.myapp.localhost不会悄悄回退到myapp.localhost。设PORTLESS_WILDCARD1可恢复未注册子域回退父路由的宽松行为。另一件默认行为portless 会自动同步/etc/hosts目的是让 Safari 这类不走浏览器内置.localhost解析的环境也能打开页面。如果你自己管理 hosts 文件或处于受限环境设PORTLESS_SYNC_HOSTS0即可旁路实现见 hosts.ts。让手机直接打开开发页LAN 模式的两个变量真机调试时手机和电脑不在同一个 loopback 上myapp.localhost根本到不了手机。PORTLESS_LAN1让代理绑定0.0.0.0/::并通过 mDNS 发布name.local主机名——同一 Wi-Fi 下的手机直接访问https://myapp.local就能看到你的开发页PORTLESS_LAN1 portless执行后每次启动默认进 LAN 模式写进 shell 配置就是长期行为。VPN、多网卡会让自动探测拿错 IP这时用PORTLESS_LAN_IP固定PORTLESS_LAN_IP192.168.1.50 portless执行后代理会绑定你指定的这块网卡地址探测逻辑被跳过。 portless 会记住LAN 模式停止后重启仍是 LAN 模式临时想切回.localhost只需单次加PORTLESS_LAN0。把开发页发给同事和公网Tailscale、Funnel、ngrok 三个开关演示、联调、外部同事要看你的本地应用又不想改框架配置比如basePath三个变量都是设1生效设1后的效果应用里读到的 URL 变量前提PORTLESS_TAILSCALE在 Tailscale 内网tailnet分享给所有设备PORTLESS_TAILSCALE_URLtailscale CLI 已安装、已连接并开启 HTTPS 证书PORTLESS_FUNNEL通过 Tailscale Funnel 暴露公网隐含 tailscalePORTLESS_TAILSCALE_URL同上PORTLESS_NGROK通过 ngrok 暴露公网PORTLESS_NGROK_URLngrok CLI 已配置 authtokenPORTLESS_FUNNEL1 portless myapp启动后portless list会同时显示本地 URL 和分享 URL应用退出时隧道自动清理不用手动收尾。一句话把开关写进~/.bashrc或.env即全局生效不用每条命令都拖着。应用代码怎么读自己的 URLportless 注入的变量portless 启动子进程时自动注入一批变量应用代码直接读就行不用硬编码地址注入的变量内容典型值PORTLESS_URL应用的主 URLhttps://myapp.localhostPORT应用应监听的临时端口4321HOST通常为127.0.0.1Expo LAN 模式下省略—NODE_EXTRA_CA_CERTSportless 本地 CA 路径HTTPS 时—PORTLESS_TAILSCALE_URLTailscale 地址启用分享时https://dev.tail1234.ts.netPORTLESS_NGROK_URLngrok 地址启用时https://abc.ngrok.app注入逻辑在 cli.ts。 典型用法——OAuth 回调地址不再硬编码const baseUrl process.env.PORTLESS_URL || http://localhost:3000;这样回调地址在本地、LAN、隧道三种环境下都正确。完整集成方式见 OAuth 技能说明。不想走代理PORTLESS0 旁路的边界在哪除了带星号的变量还有一个隐藏主角——不带星号的PORTLESSPORTLESS0 pnpm dev执行后命令原样直接运行完全绕开 portless 代理原始输出直接可见。适用场景调试代理本身、跑vite build这类不需要路由的任务、或临时想看未经加工的输出。边界要分清楚portless proxy、portless clean这类子命令不受旁路影响始终正常执行子命令的退出码会原样透传。行为见 旁路测试 与 命令参考。一台机器跑两套代理用 PORTLESS_STATE_DIR 隔离状态把代理装成开机自启服务时环境变量会被固化进服务定义这就给双份代理留了口子PORTLESS_STATE_DIR~/.portless-lan PORTLESS_LAN1 portless service install装完后这套服务的所有状态文件routes.json、proxy.pid等都落在~/.portless-lan默认那套仍住在~/.portless实现见 service.ts。这样同一台机器可以同时跑日常.localhost代理和独立 LAN 代理两套状态互不干扰。常用组合命令卡与动手前自查清单⚠️ 最常见的情况先说改了环境变量但代理没变化已有代理正在运行时portless 会警告并要求你先portless proxy stop——新变量只对新启动的代理生效。常用组合按需复制PORTLESS_PORT8443 portless proxy start PORTLESS_APP_PORT3100 portless myapp next dev第一条给代理换端口免 sudo第二条固定应用端口。PORTLESS_LAN1 portless PORTLESS_FUNNEL1 portless myapp第一条进 LAN 模式给手机用第二条开 Funnel 公网分享。PORTLESS_STATE_DIR~/.portless-lan PORTLESS_LAN1 portless service install PORTLESS0 pnpm dev第一条装一套独立状态的 LAN 服务第二条临时旁路代理。动手前自查五条PORTLESS_PORT非法值会被静默忽略回落 443/80PORTLESS_APP_PORT非法值会报错退出。两者取值都必须是 1–65535 的数字。优先级显式环境变量 portless.json 上次运行记忆。怀疑配置冲突时先确认 shell 里没有同名变量。PORTLESS_TLD避开.local撞 mDNS和.devGoogle 持有、HSTS 风险推荐.test。开分享前确认tailscaleCLI已连接、HTTPS 证书或ngrokCLIauthtoken就绪否则隧道起不来。代理在跑时改变量无效——先portless proxy stop再带着新变量启动。【免费下载链接】portlessReplace port numbers with stable, named local URLs. For humans and agents.项目地址: https://gitcode.com/GitHub_Trending/por/portless创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考