portless

当 localhost:3000 成为历史：portless 如何让本地开发 URL 稳定、可读、跨设备

想象这样一个场景：你的团队正在开发一个包含前端、后端、API 网关的微服务项目，每个人都开着七八个本地服务窗口。"API 服务跑在哪个端口？3001 还是 8080？"、"那个 OAuth 回调为什么一直失败，是不是端口换了？"—这类对话每周都在消耗着开发者宝贵的注意力。

portless 正是为解决这些"端口烦恼"而生的开源工具。它由 Vercel Labs 开发维护，通过将随机端口号替换为稳定、可读的本地域名，让每个本地服务都有一个像 https://myapp.localhost 这样的固定地址。GitHub 收获了超过 9500 颗星，是本地开发工具领域近年来备受关注的新秀。

背景故事：为什么端口管理是个真实的痛点

在日常开发中，端口号的存在感本不应该这么强。然而当项目规模扩大、服务数量增加时，端口冲突、记忆成本、Cookie 污染、浏览器历史混乱等问题接踵而至。尤其在 monorepo（单体仓库）项目中，每个 package 可能各自占用一个端口，开发者需要在 mental map 中维护一长串端口映射关系。

更糟糕的是，AI 编程助手在处理本地开发服务器时，往往只能猜测端口号，导致 API 请求打到错误的地址。portless 在其 AGENTS.md 中特别强调了这个使用场景——它是第一个从设计层面就将"AI Agent 可用性"纳入核心考量的本地开发工具。

核心原理：本地 HTTPS 代理

portless 的工作方式可以类比为一个"本地的 DNS 服务器 + 反向代理"。启动时，它会在本机 443 端口（macOS/Linux 需要 sudo 权限）运行一个 HTTPS 代理，并自动生成一个本地受信任的 CA（证书颁发机构），从而实现零警告的本地 HTTPS 环境。

当你运行 portless myapp next dev 时，portless 会自动完成以下步骤：

1. 分配一个空闲端口（4000-4999 范围）给应用
2. 启动 HTTPS 代理，将 myapp.localhost 的流量转发到该端口
3. 自动注入 PORT 环境变量，让框架自动监听正确端口
4. 更新 /etc/hosts（macOS/Linux）或注册表（Windows），确保 DNS 解析正常

整个过程对开发者完全透明，你只需要像平常一样启动开发服务器，剩下的 portless 全包了。

亮点功能

HTTPS + HTTP/2 默认开启：浏览器限制 HTTP/1.1 每个主机只能并发 6 个连接，这让 Vite、Nuxt 等开发服务器的文件分发变慢。portless 默认启用 HTTP/2，一个连接搞定所有请求，体验接近生产环境。

Monorepo 全家桶支持：只需在根目录配置一次 portless.json，workspace 下的所有包自动获得各自的域名：https://web.myapp.localhost、https://api.myapp.localhost……Turbo 用户甚至不需要修改 turbo.json，只需把 dev 脚本改为 portless，剩下的交给 portless 自动发现。

Git Worktree 自动感知：在 linked worktree 中，portless 自动在子域名加上分支名前缀，每个 worktree 获得独立 URL 而无需任何配置变更。"fix-ui" 分支的 worktree 自动获得 https://fix-ui.myapp.localhost，主分支则是 https://myapp.localhost，零冲突。

跨设备共享（LAN 模式）：通过 --lan 参数启动 mDNS 发现，同一 Wi-Fi 网络下的手机、平板可以直接访问你的本地服务，地址形如 https://myapp.local。结合 Tailscale，甚至可以把能力扩展到互联网上的队友，用于实时预览和协作调试。

AI Agent 友好：这是 Vercel Labs 特别强调的使用场景。portless 提供稳定的命名 URL，配合 PORTLESS_URL 环境变量，让 AI agent 能可靠地找到正确的服务。团队可以在项目中内置 skills/portless/SKILL.md，让 AI agent 直接理解如何使用 portless，降低 AI 辅助开发中的"端口猜测"错误率。

系统服务化：通过 portless service install，代理可以在 OS 启动时自动运行，重启后依然有效。配合 LAN 模式，开发机可以变成长期可用的本地开发服务器，团队成员随时访问。

自动修复 Safari DNS：Safari 对 .localhost 子域名的解析有时不可靠，portless 提供了 portless hosts sync 命令，将路由直接写入 /etc/hosts，彻底解决 Safari 用户的后顾之忧。

循环代理检测：如果你的前端代理配置有误（Host 头未重写），portless 能检测到 508 Loop Detected 错误并给出修复建议，防止无尽的请求循环。

技术架构

portless 采用 pnpm workspace monorepo 结构，使用 Turborepo 管理构建任务，核心代码在 packages/portless/src/ 下，约 30 个 TypeScript 源文件，含完整的 Vitest 测试覆盖。

源码按职责划分清晰：

• proxy.ts / proxy.test.ts：核心反向代理逻辑，处理 HTTP/2、TLS 终止、请求路由
• certs.ts：本地 CA 生成、证书管理、跨平台系统信任存储操作（Linux/macOS/Windows）
• hosts.ts：跨平台 hosts 文件读写，支持 Debian/Ubuntu、Arch、Fedora/RHEL、openSUSE、macOS、Windows
• service.ts：launchd（macOS）/systemd（Linux）/Task Scheduler（Windows）服务管理
• config.ts：配置文件解析（支持 portless.json 和 package.json 的 portless 字段）
• workspace.ts：monorepo 工作区自动发现，支持 pnpm workspaces 和 npm/yarn workspaces
• turbo.ts：Turborepo 进程管理和命令注入
• tailscale.ts：Tailscale serve/HTTPS 功能集成，支持 --tailscale 和 --funnel 参数
• mdns.ts / lan-ip.ts：LAN 模式的 mDNS 发布和 IP 自动跟随
• auto.ts：框架自动检测与端口/主机参数注入，支持 Vite、Expo、React Native、Angular、Next.js 等主流框架

构建工具使用 tsup（比 tsc 快），测试框架用 Vitest，代码风格工具链为 ESLint + Prettier，TypeScript 版本严格（typescript-eslint），整体工程化水平很高。

上手体验

安装只需一条命令：npm install -g portless（需要 Node.js 24+）。之后在你的项目目录下运行 portless 或 portless myapp next dev，几秒钟后就能在浏览器访问 https://myapp.localhost。HTTPS 证书首次运行自动生成并加入系统信任存储，全程无浏览器警告。

对于 monorepo 项目，只需在根目录放一个 portless.json，运行 portless 即可一键启动所有有 dev 脚本的 workspace 包，每个获得各自的子域名。

局限与争议

需要 Node.js 24+：这个要求相对较高，很多项目的 Node 版本仍停留在 18-22。Vercel Labs 选择激进地使用最新 Node 特性，对老项目升级有一定压力，也限制了 portless 在企业内网的适用范围。

macOS/Linux 需要 sudo：绑定 443 端口需要管理员权限，portless 会自动调用 sudo，但频繁的权限提示可能让人厌烦。Linux 用户还需要额外安装 avahi-utils 才能使用 LAN 模式的 mDNS 功能。

不是通用的反向代理：portless 专注本地开发场景，不适合生产环境使用。对于需要负载均衡、公网暴露等场景，应使用 nginx、Caddy 或云服务。

Monorepo 配置有一定学习成本：虽然基础使用极其简单，但 monorepo + Turborepo + Git Worktree 的组合配置对新手而言需要一定理解成本。

行业意义

portless 的出现反映了一个趋势：随着 AI 编程工具（如 GitHub Copilot、Cursor）的普及，开发工具对"可预测性"的要求提高了——AI agent 需要稳定的 URL 来可靠地访问本地服务，而不是依赖随机端口号。Vercel Labs 敏锐地捕捉到了这个需求，将 portless 打造成第一个在"AI 友好本地开发"这个细分赛道上具有工业级质量的产品。

GitHub 超过 9500 颗星、Vercel Labs 背书，加上详尽的文档（README + SKILL.md + AGENTS.md + 官方 Next.js Docs 网站）和完整测试覆盖率，portless 已经成为现代前端/全栈开发工作流中值得关注的效率工具。它的设计理念——让机器（和 AI）与人类一样，使用稳定的、可预测的地址来访问本地服务——可能会影响未来更多开发工具的设计方向。

图1：portless 由 Vercel Labs 开发和维护（Vercel Labs GitHub 头像）