---
title: "自动发现与页面验证"
description: "了解 LocalStack 如何发现本地 HTML 服务，以及为什么有些端口不会出现在列表中。"
---

> Documentation Index
> Fetch the complete documentation index at: https://localstack.pwp.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 自动发现与页面验证

LocalStack 关心的是可在浏览器中打开的开发页面。服务通过自动发现或主动注册进入验证流程，最终都由同一个 Coordinator 判断。

## 自动发现

1. 枚举当前用户启动的 TCP 监听进程。
2. 在 loopback 地址上检查候选 HTTP 服务。
3. 独立确认页面返回可浏览的 HTML，并验证进程身份与端口归属。
4. 将有效服务合并到注册表，持续检查健康状态。

普通本地 HTTP 开发服务器只要能返回 HTML，就可以被发现，不限定于特定前端框架。

## IPv4 与 IPv6 归属

Coordinator 同时核对实际监听地址与端口。IPv4、IPv6 的不同进程可以共用一个端口，并作为独立服务保留。`localhost` 注册会固定为声明进程实际监听的数字回环地址，保留路径与查询参数；限制 HTTP Host 头的服务需要允许该回环地址。

## 减少无效探测

识别到可执行文件为 **Surge** 后，自动页面探测、排队探测和健康检查会在该进程整个存活期间暂停。抑制绑定 PID、用户与启动时间；即使监听端口暂时消失也不会反复探测。进程退出后恢复判断，新进程接管端口时正常验证。

Wrangler/workerd 的内部开发端点会根据当前启动参数和端口归属过滤，不会仅凭进程名排除所有 workerd 服务。进程重启或端口归属变化后会重新判断。发现代码直接读取进程与 socket 元数据，不再为每个端口启动 `lsof`。

## 主动注册

[Vite 插件与 SDK](/docs/vite)、[CLI 与 MCP](/docs/cli) 可以提交 PID、端口、名称和项目路径。注册请求不能跳过页面和进程验证。

SDK 和插件使用有期限的租约维护注册状态。插件自动发送 heartbeat，并在 Coordinator 重启后重新注册；开发服务器关闭时会尝试注销。

## 为什么站点没有出现？

依次检查：

- **页面是否能打开？** 在浏览器中直接访问本地 HTTP URL，确认服务已经启动完成。
- **返回的是 HTML 吗？** 只有 JSON 的 API、数据库、消息队列和普通 TCP 端口不在默认列表中。
- **是不是当前用户的进程？** 其他用户运行的服务不在发现范围。
- **地址是否是本机 loopback？** LAN 地址或远程站点不在发现范围。注册接口接受 `http://localhost`、`http://127.0.0.1` 与 `http://[::1]`；不支持 HTTPS 注册。
- **是否被主动排除？** Surge 进程和已识别的 workerd 内部端点不会进入普通页面探测。
- **Coordinator 是否在线？** 启动 LocalStack 应用；如果安装了 CLI，运行 `localstack status` 查看状态。

服务启动后可以在面板按 `⌘ R` 刷新。Vite 项目需要自定义名称或非根路径时，可以使用 [插件配置](/docs/vite)。

Source: https://localstack.pwp.sh/docs/discovery