本地开发还在记端口号？Vercel Labs 出品的 Portless 想让 AI Agent 和你都别再猜端口

器匠·开发者工具 技术创作者 2026-09-03 329 阅读

本地开发时，你有没有被这些问题折磨过：

  • 记不清某个服务跑在 3000、8080 还是 5173
  • 关掉一个项目再开另一个，发现浏览器 tab 里的内容”串台”了
  • 微服务项目里 8 个端口来回切换，每次都要重新查文档
  • AI 编程 Agent 猜测端口号，结果跑到了错误的服务上

Vercel Labs 出的 Portless（11,882 ★）就是来解决这个问题的。它做的事情一句话就能说清：把 localhost:3000 这种端口号，换成 https://myapp.localhost 这种稳定命名的 URL。

它怎么工作的

安装很简单：

npm install -g portless

然后把 package.json 里的启动命令包一层：

- "dev": "next dev"
+ "dev": "portless run next dev"

执行之后，应用就跑在 https://myapp.localhost 上了，而不是 http://localhost:3000。HTTPS + HTTP/2 默认开启，首次运行会自动生成并信任本地 CA 证书。

背后的逻辑是：Portless 在 443 端口起一个反向代理，每个应用被分配一个随机高端口（4000-4999），代理负责把命名 URL 转发过去。这个端口是自动分配的，不需要你记，也不需要你配。

它对 AI 编程 Agent 特别友好

这是 Portless 真正值得关注的点。

AI 编程 Agent（Claude Code、Codex 等）在跑测试或操作浏览器时，经常需要知道”服务跑在哪个端口”。在微服务项目里，它们往往会猜错——比如认为前端在 3000、API 在 8080，但实际配置可能完全不同。

用 Portless 之后，每个服务有确定的命名 URL，Agent 不需要猜端口，也不需要读配置文件去找端口配置。这让 AI 执行自动化任务时的可靠性大幅提升。

v0.15.6（2026-08-24）还专门加了 Agent-readable 文档：文档站点现在暴露干净的 Markdown 页面和 llms.txt 索引，AI Agent 可以直接消费文档内容。Vercel 官方显然在认真对待”让 AI Agent 用这个工具“这个场景。

对主流框架的适配很宽

Portless 不是只支持 Node.js 生态。它会检测框架类型，自动注入正确的 --port 和 --host 参数：

自动适配的框架：Next.js、Express、Nuxt（自动读取 PORT 环境变量）

额外处理的框架：Vite、VitePlus、Astro、React Router、Angular、Expo、React Native——这些框架默认会忽略 PORT 环境变量，Portless 会自动补上对应的命令行参数。

对于 Expo，Portless 还保留了 --localhost、--lan、--tunnel 等连接模式参数，不会冲突。

另外，Portless 会跳过不相关的命令，比如 vite build、vite optimize、astro check 不会被注入端口参数——因为这些不是”启动服务”的命令。

Monorepo 场景：一个命令起所有服务

在 Monorepo 里，Portless 支持一次性启动多个 workspace 包。在根目录的 portless.json 里配置：

{
  "apps": {
    "apps/web": { "name": "myapp" },
    "apps/api": { "name": "api.myapp" }
  }
}

然后在仓库根目录运行 portless，所有带 dev 脚本的包都会启动，分别获得 https://myapp.localhost 和 https://api.myapp.localhost。如果是 pnpm monorepo，配合 turborepo 使用也不需要改 turbo.json。

谁该用，谁该等

适合用：

  • 同时跑 3 个以上本地服务的开发者
  • 需要让 AI 编程 Agent 稳定操作本地服务的团队
  • 经常需要把本地 URL 分享给同事或 webhook 回调的场景
  • 讨厌记端口号、受够了 EADDRINUSE 的人

不需要用：

  • 只跑单个项目、端口固定不冲突的个人开发者
  • 生产环境完全不需要这个（它只解决本地开发问题）
  • Windows 用户需要稍微折腾一下（v0.15.6 刚修了一个 Windows 服务注册的问题，但整体体验比 macOS/Linux 差一些）

稳定性和升级注意

Portless 目前是 pre-1.0 版本，官方在 release notes 里也提到了：不同贡献者可能运行不同版本，状态目录格式可能在版本间变化，如果遇到问题可能需要重新跑 portless trust。

升级时建议看一下 GitHub Releases 的 changelog，最近几个版本主要在修 Windows 支持和 Ctrl+C 进程清理，核心逻辑已经比较稳定。

下一步建议

如果被端口管理折磨过，值得花 5 分钟试一下：

npm install -g portless
cd your-project
portless run npm run dev

访问 https://yourproject.localhost，感受一下”不再需要记端口”是什么体验。

文档地址：https://portless.sh，里面有完整的配置选项和 monorepo 指南。

GitHub：https://github.com/vercel-labs/portless

  • 你本地开发时被端口问题折磨过吗？用过什么解法？欢迎分享。*

评论区

0 条评论

登录后可评论。

器匠·开发者工具 329 阅读