portless：告别 localhost 端口混乱，用稳定命名 URL 访问本地服务
portless 是 Vercel Labs 出品的 CLI 工具：用稳定好记的命名 URL（https://myapp.localhost）替代 localhost:3001 这类数字端口，减少应用端口冲突 与"端口轮盘"。代理架构实现，支持本地 HTTPS。本文讲清原理与用法。
直接回答：portless 是 Vercel Labs 的开源 CLI，把不可预测的数字端口换成稳定、好记的命名 URL——项目永远固定在 https://myapp.localhost 访问，不再翻哪个应用占了 3000 还是 3001，在名称、代理配置和工作目录约定保持一致时减少端点漂移。
localhost 端口的慢性折磨
多项目并行开发的日常：前端、后端、微服务同时起，终端一片繁忙，而底层有个低级的持续烦恼——
- EADDRINUSE：端口被占，服务起不来
- 端口轮盘：每次都在猜 myapp 今天在 3000 还是 3001
- 书签失效、API 端点要反复改、自动化脚本因端口漂移而断
这些小挫败日积月累是真实的时间与认知开销，对需要可预测端点的 AI Agent 工作流更是硬伤。
上手
npm install -g portless
portless myapp npm run dev
此后访问 https://myapp.localhost——无论应用实际监听哪个端口。名称稳定，代理为应用分配端口；应用必须遵守 PORT 或受支持框架的端口参数，代理自身的 443 等端口仍可能冲突。
底层原理：代理架构
portless 在本机跑一个轻量代理，按 Host 头把 *.localhost 域名路由到对应应用的真实端口。应用照常监听端口，portless 在外面包一层稳定命名——自定义或复合启动脚本可能无法自动注入端口，需显式适配。
进阶：本地 HTTPS 与框架注意
当前官方 README 默认启用 HTTPS/HTTP2，会创建并信任本地 CA，macOS/Linux 绑定 443 时可能请求 sudo；安装前理解系统信任变更。用 --no-tls 可改 HTTP，重启可能复用之前代理配置，以实际输出 URL 为准。Host 校验仅放行实际使用的本地主机名，不用 allowedHosts: true。不要将开发代理或密钥暴露公网。
适合谁
- 同时维护多个项目的全栈开发者
- 被端口冲突打断过的每一个人
- 搭建需要可预测本地端点的 AI Agent 工具链的团队
常见问题（FAQ）
Q：.localhost 域名需要改 hosts 文件吗？
A：不需要。多数现代浏览器识别 .localhost 回环约定，但不同 DNS/CLI 客户端仍需验证；当前工具也可同步 hosts，可能需要系统权限，portless 直接利用这一约定。
Q：和 nginx 本地反代有什么区别？
A：理念相同，但 nginx 要自己写配置、改端口要改配置；portless 一条命令完成命名映射，零配置文件。
Q：团队协作能统一吗？
A：可以——把 portless myapp npm run dev:app 写进 package.json 的 scripts，全团队同一项目同一名字，需锁定工具版本和命名约定，尤其注意 worktree 可能增加分支子域名。
官方参考
本文依据官方文档整理，示例未在本文中进行运行验证。生产部署需按所用版本、权限和实际负载验证。
