portless

Portless 集成

用于本地开发的命名 .localhost URL。将 localhost:3000 替换为 https://myapp.localhost。

完整的 CLI 参考：加载 Read("references/upstream.md")，查看完整的命令文档。

2026-04 → 2026-07 新增内容（portless 0.10.x → 0.15.0）

• portless doctor (0.15.0) — 只读诊断会检查 Node.js、状态目录、代理是否正常运行、路由条目、主机名解析、HTTPS CA 信任和局域网前置条件，然后输出建议的修复方法。在提交问题前，或 .localhost URL 无法解析时运行。
• HTTP/2 Host 转发修复（0.15.0） — 代理现在会将 HTTP/2 的 :authority 作为 Host 转发给 HTTP/1.1 后端，修复读取 Host 的应用此前在浏览器流量中看到 127.0.0.1 的问题。--force 接管清理现在只会移除仍由退出进程拥有的路由，因此强制接管不再注销新所有者的路由。
• --ngrok 标志（0.14.0） — 通过 ngrok 公开分享应用，同时本地访问仍使用其 .localhost URL。需要公开 URL、又不想放弃命名子域名开发体验时，可与现有的 Tailscale/Funnel 选项搭配使用。
• 需要 Node.js 24+（0.13.1，重大变更） — 代理和 CLI 现在要求 Node.js 24 或更高版本；不再支持较旧的运行时。本次发布还增强了启动服务的持久化功能，使 .localhost URL 能可靠地在重启后继续使用。
• 状态目录迁移至 ~/.portless（0.11，重大变更） — 状态从分散的临时位置迁移至 ~/.portless；可通过 PORTLESS_STATE_DIR 覆盖。不会自动迁移 0.11 之前安装版本的旧状态。
• OS 启动服务（0.13.0） — portless service install / service status / service uninstall 可在 macOS launchd、Linux systemd 和 Windows Task Scheduler 中注册原生启动服务，为 HTTPS 代理提供服务。无需手动运行 portless proxy start，.localhost URL 即可在重启后继续使用。portless clean 会在清理 CA 和 hosts 的同时移除该服务。
• Tailscale 就绪预检（0.13.0） — --tailscale 和 --funnel 现在会在启动子进程前验证 Tailscale HTTPS 和 Funnel 的前置条件，及时给出可操作的错误信息，避免注册时一直挂起。
• Tailscale 集成（0.12.0） — --tailscale 会通过 tailnet 分享应用，并在 443 端口自动启用 HTTPS；--funnel 则通过 Tailscale Funnel 公开应用。应用会收到 PORTLESS_TAILSCALE_URL，以便引用自身的公开地址。portless list 现在会显示 tailnet URL。
• 零配置模式（0.11.0） — 单独运行 portless 会自动从 package.json 发现开发脚本。多应用 monorepo 会自动分配子域名；并已接入 Turborepo 任务图集成。支持 portless.json 配置文件。--script 可覆盖默认的 "dev" 脚本。
• portless prune — 移除孤立的开发服务器和过期的 Tailscale 注册。
• portless clean（扩展） — 现在会在清理 CA 和 hosts 的同时，也清除 Tailscale 注册。
• Rsbuild + VitePlus 自动注入端口 — 与 Vite/Next 一样自动配置。
• 状态目录迁移至 ~/.portless（原本分散在各处）。
• 默认在 443 端口启用 HTTPS（相较于 0.9.x 的 http:1355 属于重大变更）。证书有效，无需设置。使用 --no-tls 可恢复原状。
• **自动注入 NODE_EXTRA_CA_CERTS（0.10.2）**到子进程 — Node.js HTTPS 调用无需设置即可信任 portless CA。
• --wildcard 子域名 — 为多租户 / 预览路由提供 https://*.myapp.localhost。
• portless alias <name> <port> — 将 docker-compose / emulate 端口映射到命名 URL，无需长期运行 run 进程。
• portless clean — 完全清理：停止代理、移除 CA、清除状态并清理 /etc/hosts。
• --lan 模式 — mDNS .local 主机名可通过 Wi-Fi 在手机、平板和其他机器上访问，无需配置路由器。
• 固定应用端口 — 对需要已知端口的工具（调试器、docker），可使用 --app-port 3000 / PORTLESS_APP_PORT。
• 默认启用 hosts-sync，以兼容 Safari（通过 PORTLESS_SYNC_HOSTS=0 禁用）。
• HTTP/2 HMR 修复，适用于 Vite/VitePlus/Next.js 开发 — websocket 升级在 h2 下不再失效。
• 支持 Expo / React Native — portless run expo start 可为 Metro 提供稳定的 URL，用于生成设备二维码。

适用场景

• 启动供 Agent 或浏览器测试访问的开发服务器
• 在本地运行多个服务（API + 前端 + 文档）
• 使用 Git 工作树（以分支命名的子域名）
• 本地 OAuth 流程（稳定的回调 URL）
• 将 emulate API 模拟连接到命名 URL

快速开始

# Instead of: npm run dev (random port)
portless run npm run dev
# → https://myapp.localhost (stable, named, HTTPS on 443 — default in 0.10+)

# Multi-service
portless run --name api npm run dev:api
portless run --name web npm run dev:web
# → https://api.localhost, https://web.localhost

# LAN mode (0.10.0) — reachable from phone/tablet via mDNS
portless proxy start --lan
portless run npm run dev
# → https://myapp.local (resolves across the local network, no router config)

# Full teardown (0.10.1) — stops proxy, removes CA, wipes state, cleans /etc/hosts
portless clean

# Boot persistence (0.13.0) — install native startup service (launchd / systemd / Task Scheduler)
portless service install
portless service status
# Removed automatically by `portless clean`, or explicitly:
portless service uninstall

**0.10.x 重大变更：**默认值从 https://app.localhost 切换为使用 443 端口的 https://app.localhost。使用 --no-tls 可恢复原设置。NODE_EXTRA_CA_CERTS 会自动注入子进程（0.10.2）——无需手动设置证书。/etc/hosts 会自动同步，以支持 Safari；使用 PORTLESS_SYNC_HOSTS=0 可禁用此功能。

特定框架的设置

加载 Read("references/framework-integration.md") 查看完整的框架配置方案。

大多数框架（Next.js、Vite、Express）都可通过 portless run <cmd> 运行。有些框架需要显式指定标志：

框架	自动检测？	所需额外标志
Next.js	是	无
Vite / Astro	是	无
Express / Fastify / Hono	是	无（读取 PORT 环境变量）
Ruby on Rails	是	无
FastAPI / uvicorn	否	--port $PORT --host $HOST
Django	否	$HOST:$PORT 位置参数

为什么使用 .localhost？

功能	.localhost (RFC 6761)	127.0.0.1:PORT	/etc/hosts 技巧
无需编辑 /etc/hosts	是	是	否
使用有效证书的 HTTPS	是	否	手动设置
通配符子域名	是	否	否
适用于所有浏览器	是	是	因情况而异
各服务间隔离 Cookie	是	否	是
无端口冲突	是	否	是

关键环境变量

portless 运行命令时，会注入以下变量：

变量	值	在 Agent 中的用途
PORT	分配的临时端口（4000-4999）	仅供内部使用
HOST	127.0.0.1	仅供内部使用
PORTLESS_URL	https://myapp.localhost	在 Agent 提示词中使用此变量
NODE_EXTRA_CA_CERTS	portless CA 的路径（0.10.2 起自动注入）	子 Node 进程无需设置即可信任 portless 证书

环境变量开关

变量	效果
PORTLESS=0	完全绕过 portless（CI）
PORTLESS_SYNC_HOSTS=0	禁用自动同步 /etc/hosts（默认：0.10.1+ 中启用）
PORTLESS_STATE_DIR	覆盖状态目录（默认：~/.portless；使用特权端口时为 /tmp/portless）

OrchestKit 集成模式

1. Agent 可访问的开发服务器

# Start with portless, then agents can target PORTLESS_URL
portless run npm run dev

# In ork:expect or agent-browser:
agent-browser open $PORTLESS_URL

2. Emulate + Portless（命名 API 模拟）

# Register emulate ports as named aliases
portless alias github-api 4001
portless alias vercel-api 4000
portless alias google-api 4002

# Now agents can target:
#   https://github-api.localhost — GitHub emulator
#   https://vercel-api.localhost — Vercel emulator

3. Git 工作树开发

# In worktree for feature/auth-flow:
portless run npm run dev
# → https://auth-flow.myapp.localhost (auto branch prefix)

4. 在 CI 中绕过

# Disable portless in CI — direct port access
PORTLESS=0 npm run dev

反模式

不要这样做	建议做法
在测试中硬编码 localhost:3000	使用 PORTLESS_URL 或 process.env.PORTLESS_URL
在 CI 中运行 portless	在 CI 环境中设置 PORTLESS=0
在 AGENTS.md 中使用数字端口	记录 portless URL

参考资料

文件	内容
references/upstream.md	完整的 portless CLI 参考（与 Vercel 同步）
references/upstream-oauth.md	使用稳定 URL 的 OAuth 回调模式
references/framework-integration.md	框架配置方案（FastAPI、Django、Docker、注意事项）
checklists/new-project-setup.md	分步指南：在新项目中添加 portless