Portless 本地命名路由
Portless 入门：应用名称、框架参数与可核验的首次请求
从一个命名开发应用开始，分清代理端口和应用端口，并排查无法自动注入框架参数的包脚本。
你将学会
- 从能够解释的命令开始
- 自动参数注入只识别有限语法
- 先证明路由，再增加便利功能
开始前需要
- 了解 HTTP 访问源、端口和命令行基础
- 能够区分回环、局域网与公网暴露
追踪命名请求，明确安装权限边界，并区分已观察行为和未测试集成。
先看结论
- 代理端口和应用端口解决不同问题。
- 无法归类的 shell 脚本不会被静默重写。
- 排查失败请求时，以真实监听和路由表为证据。
从能够解释的命令开始
上游入门方式是安装 Portless，再用明确名称加开发命令启动，例如 portless myapp next dev。这属于安装和本地配置操作，不是只读诊断。在工作机器运行前，应检查包版本、Node.js 24 要求，以及首次证书配置需要的权限。下面命令只是用户主动选择的示例，并非本次审查已经执行的操作。
若要先做权限较少的 HTTP 练习，可以禁用 TLS，在 1355 端口启动代理，再在第二个终端启动临时应用。浏览器网址要包含 :1355；这是代理端口，不是动态分配的应用端口。HTTP 适合排查路由，但不能等价验证 Secure Cookie、证书信任和所有浏览器能力。
自动参数注入只识别有限语法
Portless 为子进程设置 PORT。对于需要命令行参数的受支持框架，cli-utils.ts 会补充缺失的 --port，某些情况下还会补充 --host。它会区分提供服务的命令与构建、检查等操作；不能因为识别到了 Vite 可执行文件，就把开发服务器端口塞给构建命令。原本明确指定的端口和主机参数也会影响处理。
带环境变量前缀、转调其他脚本、复合 shell 命令、末尾注释或自身选项终止符的包脚本，可能保持原样。这避免参数被附加到错误命令，或落入注释而失效。若打印的后端端口和实际监听不一致，应简化脚本或明确配置端口，不要指望反复重启代理能解决语法识别限制。
先证明路由，再增加便利功能
检查 portless list，并使用文档说明为只读的 portless doctor 做健康诊断。确认应用已经运行，再核对浏览器中的协议、名称和代理端口。代理返回的 404 通常意味着没有匹配路由，502 则意味着选定的回环后端无法到达；将它们一概归因于 DNS 之前，应先检查应用输出。
明确名称的案例成功后，再考虑用 portless run 推断名称和工作树前缀。让首次实验保持可逆：只停止自己的临时应用与代理，不清理其他人共用的状态。回环库实验验证的是路由行为，并没有覆盖完整安装流程，也没有在所有操作系统验证全部框架参数组合。
实施步骤
- 1
仅在批准的开发环境检查并安装选定版本。
- 2
先用非特权端口进行 HTTP 路由练习。
- 3
另开终端，以明确名称启动临时应用。
- 4
检查 list、doctor 和实际网址，再加入工作树自动化。
可复制示例
# 可选安装示例；本次审查未执行
npm install -g portless@0.15.6
portless proxy start --no-tls --port 1355
# 第二个终端，在临时 Next.js 项目内执行：
portless myapp next dev
# 访问 http://myapp.localhost:1355
portless list
portless doctor常见问题
为什么包脚本仍使用原端口？
注入器可能不识别该语法，或判断追加参数不安全。检查脚本与实际监听，简化命令或明确设置端口。
HTTP 示例能证明 HTTPS 正常吗？
不能。HTTPS 还涉及证书生成、信任和浏览器验证；接受相关本地配置变更后，需要单独测试。
资料来源
- README.md来源核查 2026-09-08
- packages/portless/package.json来源核查 2026-09-08
- packages/portless/src/cli-utils.ts来源核查 2026-09-08
- packages/portless/src/proxy.ts来源核查 2026-09-08