Portless：本地端口号换稳定命名 URL，AI 编程神器

Skill超级捕获手 技术创作者 2026-09-03 10 阅读

Portless：把本地端口号换成稳定命名 URL，AI 编程助手和人类开发者都在用

本地开发时，端口号是每个工程师心里的痛。两个项目同时跑，一个占 3000 一个占 3001，撞上了就 EADDRINUSE；换台电脑接手，README 里写的 localhost:8080 其实早就改成了 3001；AI 编程助手更惨——它读配置猜端口，一改配置全报错。portless 就是来解决这个问题的：把随机分配的端口号换成稳定的命名 URL，比如 myapp.localhost，人和 AI 都能稳定依赖。

功能与原则

portless 是一个本地 DNS 解析 + 反向代理工具，核心做两件事：为每个本地开发服务分配一个固定的 .localhost 域名（基于项目目录名），自动维护端口到域名的映射关系。它不是另一个端口管理器，而是一个本地代理层——端口可以随机分配，但对外暴露的始终是稳定命名，端口变了 URL 不变。

设计原则：零配置优先，框架自适应，多端共享。

认可度

  • GitHub Star：约 11,800+（截至 2026-09-03）
  • 今日新增：约 73 stars（GitHub Trending 当天榜单位列前排）
  • 所属：Vercel Labs（Vercel 官方团队出品）
  • 定位：今年 GitHub Trending 常客，开发工具类项目中增速显著

链接

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

原作者

vercel-labs（Vercel Labs 团队）——Vercel 官方内部孵化项目，背后维护者包括 ctate、Railly、tomdale 等资深开源工程师。定位是”给人类和 AI agent 用的本地 URL 命名工具”。

介绍

portless 的起源是本地开发中一个长期被忽视的摩擦点：端口号天然不稳定（随机分配、经常冲突），但工程师和 AI 工具都不得不在各种配置文件、测试用例、文档里硬编码它。

使用方式极其简单：

# 安装
npm install -g portless

# 启动本地代理（一次，只需 sudo 权限一次）
portless proxy start

# 用命名 URL 运行你的项目
portless myapp next dev
# → 自动路由到 https://myapp.localhost:1355

项目根目录直接运行 portless，它会自动读取 package.json 的项目名作为 URL 前缀；monorepo 场景下子项目自动生成 api.myapp.localhost、docs.myapp.localhost 等子域名，不需要任何配置。

对于 AI coding agent 来说，这解决了大问题：AI 生成的测试文件和环境变量里写的是 http://localhost:3847，但端口每次启动都会变，AI 写的代码实际运行时全部失效。portless 让 URL 恒定为 https://myservice.localhost，AI 的输出稳定可用。

特点

  • 稳定命名：项目名即域名，端口随机分配但 URL 固定，AI 和人类都能放心依赖
  • 多端共享：团队成员每人都是同一套 URL（myapp.localhost），无需问”你这服务跑在哪个端口”
  • HTTPS 默认启用：自动生成本地 CA 证书并信任，.localhost 域名的 HTTPS 开箱即用
  • Monorepo 友好：自动为每个 workspace 包分配子域名，monorepo 根目录一条命令启动全部服务
  • Git worktree 自动适配：自动检测 git worktree 并在子域名加分支名前缀（fix-ui.myapp.localhost），不同分支不打架
  • AI Coding Agent 原生支持：专为 Claude Code、Cursor 等 AI 编程工具设计，避免 AI 生成的代码里硬编码错误端口
  • 框架自适应：支持 Next.js、Vite、Express、Nuxt、Angular、Expo、React Native 等主流框架，无需手动指定端口参数

使用方法

安装

npm install -g portless

基本使用

# 方式一：在 package.json 脚本里用 portless
{
  "scripts": {
    "dev": "portless run next dev"
  }
}

# 方式二：命令行直接运行
portless myapp next dev
# → https://myapp.localhost

# 方式三：monorepo 根目录一键启动所有服务
cd /my-monorepo
portless

代理管理

# 启动本地 HTTPS 代理
portless proxy start

# 查看当前活跃路由
portless list

# 诊断问题
portless doctor

# 清除状态（重置）
portless clean

分享给队友（借助 Tailscale 或 ngrok）

# Tailscale 网络内自动共享
PORTLESS_TAILSCALE=1 portless myapp next dev

# 公网分享（ngrok）
PORTLESS_NGROK=1 portless myapp next dev

使用场景与人群

适用场景：

  • Monorepo 开发：多服务并行运行，子域名天然隔离，不需要记每个包的端口
  • 团队协作：统一 URL 规范，README 里的链接对所有人有效
  • AI Coding Agent 开发：AI 生成代码里引用稳定的命名 URL，不因端口变化而失效
  • 多项目并行：同时跑多个客户/项目的本地环境，浏览器 tab 不再混淆
  • 文档与演示：对外分享本地服务 URL，Tailscale/ngrok 一键公网暴露

目标用户：

  • 前端/全栈工程师（尤其是 monorepo 重度用户）
  • 使用 Claude Code、Cursor、Codex 等 AI 编程工具的开发者
  • 需要频繁对外演示本地项目的设计师/产品经理

输入与输出案例

案例一：Monorepo 多服务同时运行

输入命令：
cd my-workspace && portless

输出效果：
[portless] Starting proxy...
[portless] myapp       → https://myapp.localhost:1355
[portless] api.myapp  → https://api.myapp.localhost:1355
[portless] docs.myapp → https://docs.myapp.localhost:1355
浏览器分别打开这三个 URL，全部正确路由，无需记忆端口。

案例二：AI Coding Agent 生成测试文件

AI 生成的代码中包含：
const API_URL = 'http://localhost:3847/api/users';

但下次启动端口随机分配到了 4521，导致测试失败。

使用 portless 后：
const API_URL = 'http://api.myapp.localhost/api/users';
端口无论怎么变，URL 始终有效，AI 生成的代码拿来就能用。

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

评论区

0 条评论

登录后可评论。

Skill超级捕获手 10 阅读