15 个 PORTLESS_* 环境变量完整指南本地开发应用告别随机端口快速拿到稳定 HTTPS URL【免费下载链接】portlessReplace port numbers with stable, named local URLs. For humans and agents.项目地址: https://gitcode.com/GitHub_Trending/por/portlessportless 把「端口号」换成「稳定的命名 URL」运行portless myapp next dev你直接访问https://myapp.localhost不再需要记localhost:3000。它首次运行自动生成本地 CA 并绑定 443应用则拿到 4000–4999 的随机端口全部调优旋钮都集中在下面这 15 个PORTLESS_*环境变量里新手友好读完即可上手。我该看哪一节按场景对号入座443 被占、没有权限看「改端口」一节一行变量解决想用手机看开发页看「LAN 模式」一节同一 Wi-Fi 直接打开要把链接发给外人看「公网分享」一节Tailscale / ngrok 一条命令想改域名后缀或子域路由规则看「域名后缀」一节想临时绕开代理调试看「进阶」一节PORTLESS0旁路工作原理一段话说清portless 本质是一个反向代理加自动端口分配器启动应用时给它挑一个 4000–4999 的随机端口通过PORT注入应用只管监听所有外部流量走统一入口再转发进去。优先级固定显式环境变量 portless.json/package.json配置 上次运行记忆。portless myapp next dev ▼ 代理(默认 443) ── 应用(随机端口 4000-4999, 注入 PORT) ▼ https://myapp.localhost改端口代理端口、应用端口怎么固定443 被占、或没有 sudo 权限时看这里。端口冲突是本地开发最常见的报错来源portless 给了三层旋钮。变量作用默认值PORTLESS_PORT改代理端口443HTTPS/ 80HTTPPORTLESS_HTTPS设0关 HTTPS走纯 HTTP开启PORTLESS_APP_PORT固定应用端口等价--app-port随机 4000–4999PORTLESS_PORT8443 portless myapp next dev 坑非法值非数字、超范围不会报错而是被忽略、回落到协议默认端口PORTLESS_APP_PORT必须在 1–65535否则启动直接失败。解析逻辑见 packages/portless/src/cli-utils.ts。手机访问开发页LAN 模式需要同事或手机看同一个页面时看这里。PORTLESS_LAN1让代理绑定所有网卡并通过 mDNS一种局域网内的名字服务类似*.local发布name.local同一 Wi-Fi 下直接打开https://myapp.local。变量作用默认值PORTLESS_LAN设1常驻 LAN 模式关闭PORTLESS_LAN_IP固定 LAN 模式用的 IPVPN/多网卡自动探测PORTLESS_LAN1 PORTLESS_LAN_IP192.168.1.50 portless 坑portless 会「记住」LAN 模式记录在~/.portless的状态文件里停掉重启后仍是 LAN 模式想临时切回.localhost当次运行加PORTLESS_LAN0即可。公网分享Tailscale / Funnel / ngrok要把开发环境链接发给外部的人时看这里。三个变量都能不改任何框架配置如basePath就把应用发出去应用退出时隧道自动清理。变量效果注入子进程的 URLPORTLESS_TAILSCALE分享给 Tailscale 私网所有设备PORTLESS_TAILSCALE_URLPORTLESS_FUNNEL经 Tailscale Funnel 暴露公网隐含上一条PORTLESS_TAILSCALE_URLPORTLESS_NGROK经 ngrok 暴露公网PORTLESS_NGROK_URLPORTLESS_FUNNEL1 portless myapp 坑前提是装好tailscaleCLI已连接或配置好 authtoken 的ngrok否则隧道起不来URL 变量也不会注入。改域名后缀与路由规则本地 URL 对齐生产本地 URL 要和线上结构一致、或嫌子域路由太严格时看这里。变量作用默认值PORTLESS_TLD域名后缀逗号分隔多个localhostPORTLESS_WILDCARD设1允许未注册子域回退父路由严格匹配PORTLESS_SYNC_HOSTS设0关闭自动写/etc/hosts开启PORTLESS_TLDlocalhost,dev.example.com portless 坑.local在 macOS 上与 mDNS 冲突、.dev/.app被浏览器 HSTS 强制 HTTPS官方建议用 IANA 保留后缀如.test。另外 Safari 不解析.localhostportless 默认把路由主机名同步进/etc/hosts受限环境用PORTLESS_SYNC_HOSTS0旁路。进阶隐藏开关、状态隔离、让应用知道自己在哪一键旁路PORTLESS0 pnpm dev直接执行命令、完全绕开代理调试代理本身或跑vite build这类任务正合适portless proxy、portless clean等子命令不受旁路影响退出码原样透传。同机跑两套状态PORTLESS_STATE_DIR~/.portless-lan改变routes.json、proxy.pid等状态文件位置默认~/.portless「日常 .localhost」和「独立 LAN」两套代理可以并存。执行portless service install时当前环境变量会被固化进服务定义重启不丢。让应用自报地址子进程会被注入PORT要监听的端口、HOST通常 127.0.0.1、PORTLESS_URL主 URL、NODE_EXTRA_CA_CERTS本地 CA 路径HTTPS 时。OAuth 回调写成process.env.PORTLESS_URL || http://localhost:3000就再不用硬编码注入细节见 packages/portless/src/cli.ts。最容易犯的 3 个错改环境变量后立刻生效→ 代理仍在用旧配置改了等于白改 → 先portless proxy stop再启动新变量只对新代理生效。回调地址、端口写死在代码里→ 一换 LAN 模式或改 TLD 页面就挂 → 运行时读PORTLESS_URL和PORT。PORTLESS_PORT填了个不合法的值还指望它报错→ 会被静默忽略、回落 443/80端口被占时启动失败让人摸不着头脑 → 用明确的PORTLESS_PORT8443并用portless --help的输出核对当前配置。把这 15 个变量加上旁路与状态隔离用熟之后你改端口、换域名、发链接、隔离环境都只需一行环境变量。完整变量表见官方配置文档全部命令见命令参考。【免费下载链接】portlessReplace port numbers with stable, named local URLs. For humans and agents.项目地址: https://gitcode.com/GitHub_Trending/por/portless创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考