2026/9/17 8:03:17
FEATURED · 精选文章 
别再说 localhost:3000 了portless 用 15 个环境变量搞定本地开发端口管理【免费下载链接】portlessReplace port numbers with stable, named local URLs. For humans and agents.项目地址: https://gitcode.com/GitHub_Trending/por/portlessCI 里两个服务抢同一个 3000 端口改完代码忘了该刷新哪个标签页手机又连不上本地调试页——本地开发端口管理最折磨人的就是这些。portless 的思路很直接把端口号换成稳定的命名 URL跑portless myapp next dev之后永远访问https://myapp.localhost。想微调它的行为全部靠 15 个PORTLESS_*环境变量。先搞懂请求怎么流转portless 本质是一个本地 HTTPS 代理请求从哪来到哪去一张图portless myapp next dev │ ▼ 本地 HTTPS 代理默认 443──按 Host 名路由── 随机端口 4000–4999注入 PORT │ ▼ https://myapp.localhost你真正需要记住的只有三条代理默认占 443HTTPS或 80HTTP可用PORTLESS_PORT换应用拿到 4000–4999 的随机端口通过PORT注入可用PORTLESS_APP_PORT固定所有PORTLESS_*环境变量优先于portless.json和上次运行的记忆值。优先级规则一句话显式环境变量 配置文件 默认值后面所有场景都按这个顺序理解。按场景调优本地开发端口管理场景涉及变量换代理端口、关 HTTPSPORTLESS_PORT、PORTLESS_HTTPS换域名后缀、放宽子域匹配PORTLESS_TLD、PORTLESS_WILDCARD、PORTLESS_SYNC_HOSTS固定应用端口PORTLESS_APP_PORT局域网调试PORTLESS_LAN、PORTLESS_LAN_IP对外分享PORTLESS_TAILSCALE、PORTLESS_FUNNEL、PORTLESS_NGROK彻底绕过代理PORTLESS给代理换个不闹事的端口开发机上 443 常被占、80 可能还要 rootPORTLESS_PORT就是为这个准备的写进 shell 配置一次生效CI 里或没装本地 CA 时再叠一个PORTLESS_HTTPS0关掉证书代理切到纯 HTTPexport PORTLESS_PORT8443 PORTLESS_HTTPS0 portless proxy start⚠️ 两个坑PORTLESS_PORT写了非法值非数字、超范围不会报错会被静默忽略并回落到协议默认端口代理已在运行时改变量无效先portless proxy stop新值只对新启动的代理生效。端口解析逻辑见 cli-utils.ts。给本地 URL 换个域名后缀想让本地 URL 和生产结构一致比如都是dev.example.com下的子域PORTLESS_TLD支持多段域名逗号分隔可以配多个这样本地、预发、生产的 URL 结构完全一致PORTLESS_TLDlocalhost,dev.example.com portless多个 TLD 重叠时按最长后缀优先匹配。⚠️.local与 mDNS 冲突、.dev和.app被浏览器 HSTS 预载启动时会有警告官方推荐 IANA 保留的.test。路由默认是严格的——api.myapp.localhost不会回退到myapp的路由老项目依赖这种宽松行为时用PORTLESS_WILDCARD1恢复。自定义 TLD 的域名靠/etc/hosts自动同步来解析自己管理 hosts 文件或环境受限时PORTLESS_SYNC_HOSTS0一键旁路。把应用端口钉死portless 默认给应用随机分配 4000–4999大多数框架直接听PORTVite 这类不听PORT的框架也不用管portless 会自动注入--port参数。当外部工具或测试环境已经指定了端口时用PORTLESS_APP_PORT跳过随机分配PORTLESS_APP_PORT3100 portless myapp next dev⚠️ 取值必须在 1–65535否则启动直接报错退出。优先级从高到低--app-port参数 PORTLESS_APP_PORTpackage.json的portless键 portless.json 自动分配完整规则见 configuration 文档。让手机也能连开发页演示、扫码调试时手机和电脑在同一个 Wi-FiPORTLESS_LAN1让代理绑定所有网卡并通过 mDNS 发布name.local手机直接访问https://myapp.local就能看开发页PORTLESS_LAN1 portless PORTLESS_LAN_IP192.168.1.50 portless # VPN、多网卡时固定 IP portless 会记住 LAN 模式停止后重启仍是 LAN 模式想临时切回.localhost单次加PORTLESS_LAN0即可。多网卡机器自动探测 IP 不准时用PORTLESS_LAN_IP把 IP 钉死。把应用一键分享出去三个开关把本地应用发出去全都不用改框架配置如basePath。PORTLESS_TAILSCALE1分享给 tailnet 内所有设备PORTLESS_FUNNEL1走 Tailscale Funnel 暴露公网隐含 tailscalePORTLESS_NGROK1走 ngrok 公网隧道PORTLESS_FUNNEL1 portless myapp⚠️ 前提是装好对应 CLItailscale 已连接并开启 HTTPS 证书ngrok 配好 authtoken。portless list会同时显示本地 URL 和分享 URL应用退出时隧道自动清理不会留残留进程。分享相关实现见 tailscale.ts。彻底绕过代理调试代理本身、跑vite build这类不需要路由的任务、或想看原始输出时PORTLESS0让命令完全绕开代理直接执行PORTLESS0 pnpm dev注意portless proxy、portless clean等子命令不受旁路影响始终正常执行子命令的退出码原样透传。旁路说明见 commands 文档。让应用自己知道地址前面调的都是你设给 portless 的变量拉起子进程时portless 还会往应用环境里塞另一批PORT该监听的端口、HOST通常 127.0.0.1、PORTLESS_URL主 URL启用分享时还有PORTLESS_TAILSCALE_URL或PORTLESS_NGROK_URLHTTPS 时NODE_EXTRA_CA_CERTS指向本地 CA。你设的变量调 portless它塞的变量给应用读这是两件事。典型用法是 OAuth 回调地址不再硬编码// 回调地址跟随当前环境分享 URL 主 URL 兜底 const callback process.env.PORTLESS_TAILSCALE_URL || process.env.PORTLESS_URL || http://localhost:3000;注入逻辑在 cli.ts。同一台机器跑两套代理PORTLESS_STATE_DIR决定 routes.json、proxy.pid 等状态文件的位置默认~/.portless。把代理装成开机自启服务时当前环境变量会被固化进服务定义于是日常.localhost代理和独立 LAN 代理可以共用一台机器、互不干扰PORTLESS_STATE_DIR~/.portless-lan PORTLESS_LAN1 portless service install实现见 service.ts。把常用的端口和 LAN 开关写进.bashrc剩下的交给它。继续往下读环境变量配置完整说明CLI 实现入口变更记录【免费下载链接】portlessReplace port numbers with stable, named local URLs. For humans and agents.项目地址: https://gitcode.com/GitHub_Trending/por/portless创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
别再说 localhost:3000 了：portless 用 15 个环境变量搞定本地开发端口管理
别再说 localhost:3000 了portless 用 15 个环境变量搞定本地开发端口管理【免费下载链接】portlessReplace port numbers with stable, named local URLs. For humans and agents.项目地址: https://gitcode.com/GitHub_Trending/por/portlessCI 里两个服务抢同一个 3000 端口改完代码忘了该刷新哪个标签页手机又连不上本地调试页——本地开发端口管理最折磨人的就是这些。portless 的思路很直接把端口号换成稳定的命名 URL跑portless myapp next dev之后永远访问https://myapp.localhost。想微调它的行为全部靠 15 个PORTLESS_*环境变量。先搞懂请求怎么流转portless 本质是一个本地 HTTPS 代理请求从哪来到哪去一张图portless myapp next dev │ ▼ 本地 HTTPS 代理默认 443──按 Host 名路由── 随机端口 4000–4999注入 PORT │ ▼ https://myapp.localhost你真正需要记住的只有三条代理默认占 443HTTPS或 80HTTP可用PORTLESS_PORT换应用拿到 4000–4999 的随机端口通过PORT注入可用PORTLESS_APP_PORT固定所有PORTLESS_*环境变量优先于portless.json和上次运行的记忆值。优先级规则一句话显式环境变量 配置文件 默认值后面所有场景都按这个顺序理解。按场景调优本地开发端口管理场景涉及变量换代理端口、关 HTTPSPORTLESS_PORT、PORTLESS_HTTPS换域名后缀、放宽子域匹配PORTLESS_TLD、PORTLESS_WILDCARD、PORTLESS_SYNC_HOSTS固定应用端口PORTLESS_APP_PORT局域网调试PORTLESS_LAN、PORTLESS_LAN_IP对外分享PORTLESS_TAILSCALE、PORTLESS_FUNNEL、PORTLESS_NGROK彻底绕过代理PORTLESS给代理换个不闹事的端口开发机上 443 常被占、80 可能还要 rootPORTLESS_PORT就是为这个准备的写进 shell 配置一次生效CI 里或没装本地 CA 时再叠一个PORTLESS_HTTPS0关掉证书代理切到纯 HTTPexport PORTLESS_PORT8443 PORTLESS_HTTPS0 portless proxy start⚠️ 两个坑PORTLESS_PORT写了非法值非数字、超范围不会报错会被静默忽略并回落到协议默认端口代理已在运行时改变量无效先portless proxy stop新值只对新启动的代理生效。端口解析逻辑见 cli-utils.ts。给本地 URL 换个域名后缀想让本地 URL 和生产结构一致比如都是dev.example.com下的子域PORTLESS_TLD支持多段域名逗号分隔可以配多个这样本地、预发、生产的 URL 结构完全一致PORTLESS_TLDlocalhost,dev.example.com portless多个 TLD 重叠时按最长后缀优先匹配。⚠️.local与 mDNS 冲突、.dev和.app被浏览器 HSTS 预载启动时会有警告官方推荐 IANA 保留的.test。路由默认是严格的——api.myapp.localhost不会回退到myapp的路由老项目依赖这种宽松行为时用PORTLESS_WILDCARD1恢复。自定义 TLD 的域名靠/etc/hosts自动同步来解析自己管理 hosts 文件或环境受限时PORTLESS_SYNC_HOSTS0一键旁路。把应用端口钉死portless 默认给应用随机分配 4000–4999大多数框架直接听PORTVite 这类不听PORT的框架也不用管portless 会自动注入--port参数。当外部工具或测试环境已经指定了端口时用PORTLESS_APP_PORT跳过随机分配PORTLESS_APP_PORT3100 portless myapp next dev⚠️ 取值必须在 1–65535否则启动直接报错退出。优先级从高到低--app-port参数 PORTLESS_APP_PORTpackage.json的portless键 portless.json 自动分配完整规则见 configuration 文档。让手机也能连开发页演示、扫码调试时手机和电脑在同一个 Wi-FiPORTLESS_LAN1让代理绑定所有网卡并通过 mDNS 发布name.local手机直接访问https://myapp.local就能看开发页PORTLESS_LAN1 portless PORTLESS_LAN_IP192.168.1.50 portless # VPN、多网卡时固定 IP portless 会记住 LAN 模式停止后重启仍是 LAN 模式想临时切回.localhost单次加PORTLESS_LAN0即可。多网卡机器自动探测 IP 不准时用PORTLESS_LAN_IP把 IP 钉死。把应用一键分享出去三个开关把本地应用发出去全都不用改框架配置如basePath。PORTLESS_TAILSCALE1分享给 tailnet 内所有设备PORTLESS_FUNNEL1走 Tailscale Funnel 暴露公网隐含 tailscalePORTLESS_NGROK1走 ngrok 公网隧道PORTLESS_FUNNEL1 portless myapp⚠️ 前提是装好对应 CLItailscale 已连接并开启 HTTPS 证书ngrok 配好 authtoken。portless list会同时显示本地 URL 和分享 URL应用退出时隧道自动清理不会留残留进程。分享相关实现见 tailscale.ts。彻底绕过代理调试代理本身、跑vite build这类不需要路由的任务、或想看原始输出时PORTLESS0让命令完全绕开代理直接执行PORTLESS0 pnpm dev注意portless proxy、portless clean等子命令不受旁路影响始终正常执行子命令的退出码原样透传。旁路说明见 commands 文档。让应用自己知道地址前面调的都是你设给 portless 的变量拉起子进程时portless 还会往应用环境里塞另一批PORT该监听的端口、HOST通常 127.0.0.1、PORTLESS_URL主 URL启用分享时还有PORTLESS_TAILSCALE_URL或PORTLESS_NGROK_URLHTTPS 时NODE_EXTRA_CA_CERTS指向本地 CA。你设的变量调 portless它塞的变量给应用读这是两件事。典型用法是 OAuth 回调地址不再硬编码// 回调地址跟随当前环境分享 URL 主 URL 兜底 const callback process.env.PORTLESS_TAILSCALE_URL || process.env.PORTLESS_URL || http://localhost:3000;注入逻辑在 cli.ts。同一台机器跑两套代理PORTLESS_STATE_DIR决定 routes.json、proxy.pid 等状态文件的位置默认~/.portless。把代理装成开机自启服务时当前环境变量会被固化进服务定义于是日常.localhost代理和独立 LAN 代理可以共用一台机器、互不干扰PORTLESS_STATE_DIR~/.portless-lan PORTLESS_LAN1 portless service install实现见 service.ts。把常用的端口和 LAN 开关写进.bashrc剩下的交给它。继续往下读环境变量配置完整说明CLI 实现入口变更记录【免费下载链接】portlessReplace port numbers with stable, named local URLs. For humans and agents.项目地址: https://gitcode.com/GitHub_Trending/por/portless创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
