Portless Skill 技能

Portless — 用稳定命名 URL 替代本地端口号

技能简介

Portless 是 Vercel Labs 出品的开源 CLI 工具，为本地开发服务器分配稳定的命名 URL（如 myapp.localhost），同时面向人类开发者和 AI Coding Agent，彻底解决端口号混乱、冲突和硬编码等问题。GitHub Stars 10k，npm 周下载量持续增长。

核心能力（≥5条）

• 将随机端口号替换为稳定的命名 .localhost URL（如 myapp.localhost）
• 自动启动本地 HTTPS 反向代理（HTTP/2 + 自签名 CA 证书），开箱即用
• 自动检测并适配主流开发框架（Next.js、Vite、Express、Nuxt、Angular、React Router、Expo、React Native）
• 自动为忽略 PORT 环境变量的框架注入正确端口和主机参数
• 支持 Git Worktree 自动检测，Branch 名称自动前缀为子域名，每个 Worktree 获得独立稳定 URL

安装配置（≥3条）

• 全局安装（推荐）：npm install -g portless
• 项目依赖安装：npm install -D portless，通过 package.json scripts 调用
• 启动代理：portless proxy start，首次运行自动生成并信任本地 CA 证书
• 配置示例：在 package.json 中将 dev 命令包装为 portless myapp next dev

使用步骤（≥4步）

• 步骤一：安装 Portless（全局或项目依赖）
• 步骤二（首次）：运行 portless proxy start 启动本地代理，浏览器访问一次以信任本地 CA 证书
• 步骤三：在 package.json 中将开发命令包装为 portless run name command
• 步骤四：运行 npm run dev，Portless 自动分配端口并注册 URL
• 步骤五：在 AI Coding Agent 中使用稳定 URL 进行 API 调用和文档编写

适用场景（≥4个）

• Monorepo 多服务并行开发，每个服务分配独立子域名
• Git Worktree 并行对比不同分支，无需手动改配置
• AI Coding Agent 集成开发，Agent 生成的测试脚本使用稳定 URL
• 团队协作，队友间共享 myapp.localhost 无需再问端口

适用人群

• 日常运行多个本地项目的开发者
• 使用 Claude Code、Cursor 等 AI Coding 工具的工程师
• Monorepo 项目维护者

工作原理

• portless proxy start 在本地启动 HTTPS 反向代理作为后台常驻进程
• 运行 portless run 时，通过 PORT 环境变量分配随机空闲端口（4000-4999），同时将命名 URL 注册到代理
• 浏览器访问 https://myapp.localhost 时，代理将请求路由到实际开发服务器
• 对于忽略 PORT 的框架，Portless 自动解析命令并注入正确参数

官方链接

• GitHub：https://github.com/vercel-labs/portless
• npm：https://www.npmjs.com/package/portless