Laravel Herd启动失败？5招解决端口监听错误

2025-04-09 18:49:23

解决 Laravel Herd 环境下 php artisan serve 端口监听失败 (Failed to listen on 127.0.0.1:8000)

刚装好 Laravel Herd，准备用它来管理 Laravel 项目，结果遇到了点麻烦。启动 Herd 里的 Nginx 时，日志报了个错：

2024/06/05 22:20:17 [emerg] 8764#8936: bind() to 127.0.0.1:80 failed (10013: An attempt was made to access a socket in a way forbidden by its access permissions)

更让人头疼的是，在项目里跑 php artisan serve 命令，也启动不了内置服务器，终端哗啦啦打出一堆错误：

Failed to listen on 127.0.0.1:8000 (reason: ?)
Failed to listen on 127.0.0.1:8001 (reason: ?)
Failed to listen on 127.0.0.1:8002 (reason: ?)
... (一直到 8010) ...
Failed to listen on 127.0.0.1:8010 (reason: ?)

奇怪的是，之前用手动安装的 XAMPP 和 Composer 时，一切正常。换成 Herd 之后，这些问题就冒出来了。直觉告诉我可能是端口占用的问题，但我用 PowerShell 查了一遍 8000 到 8010 这些端口：

PS C:\Windows\System32> for ($port = 8000; $port -le 8010; $port++) {
>>     $connections = Get-NetTCPConnection -LocalPort $port -ErrorAction SilentlyContinue
>>     if ($connections) {
>>         Write-Output "Port $port is in use."
>>     } else {
>>         Write-Output "Port $port is free."
>>     }
>> }
>>
Port 8000 is free.
Port 8001 is free.
Port 8002 is free.
Port 8003 is free.
Port 8004 is free.
Port 8005 is free.
Port 8006 is free.
Port 8007 is free.
Port 8008 is free.
Port 8009 is free.
Port 8010 is free.

结果显示这些端口都是空闲的！防火墙也开关试过了，php.ini 文件也确认存在，甚至重启了电脑，问题依旧。

一、问题根源在哪？

看起来像是端口冲突，但检查结果又说端口是空的，这就有点迷惑人了。综合 Nginx 的 bind() failed (10013: ... access permissions) 错误和 php artisan serve 的 Failed to listen 错误，主要原因可能有这么几个：

权限不足 ： Nginx 尝试绑定的 80 端口是个特权端口（小于 1024）。普通用户程序通常没权限监听这些端口。错误代码 10013 (WSAEACCES) 明确指向了 “权限禁止访问套接字”。虽然 php artisan serve 默认用的 8000 端口不是特权端口，但在某些系统策略或安全软件的限制下，也可能遇到权限问题。
隐藏的端口占用/预留 ：虽然 Get-NetTCPConnection 没查到监听程序，但可能有其他服务或系统进程已经“预定”或“占用”了这些端口，只是没有进入 LISTENING 状态。比如 Windows 的某些服务（像 Hyper-V 或其他网络相关服务）可能会动态预留端口范围。
Laravel Herd 自身的机制冲突 ： Herd 设计的目标就是通过 Nginx 或 Caddy 来统一管理和提供本地开发环境的 Web 服务。当你尝试在由 Herd 管理的项目中手动运行 php artisan serve 时，可能会与 Herd 内部的服务管理逻辑，或者它所启动的 PHP-FPM 进程产生某种冲突或资源竞争，即使端口本身没被直接监听。Herd 可能期望自己全权处理站点的服务，而不是依赖 artisan serve。
旧环境残留 ：从 XAMPP 迁移过来，虽然你可能停用了 XAMPP，但难免有 Apache 或相关服务没彻底停止或被设置为开机自启，仍在后台偷偷占用着 80 端口或其他资源。

那个 PowerShell 检查 Get-NetTCPConnection 只能看到当前正处于 LISTENING 状态的 TCP 连接。它可能查不到某些特殊状态的端口占用，比如被某个程序绑定了但还没开始监听，或者被系统策略保留了。

二、动手解决问题

碰到这种端口监听失败，尤其是权限相关的报错，得从几个方面下手试试。

方案一：揪出并干掉冲突进程

虽然之前的检查说端口空闲，我们换个更给力的方式再查一遍，顺便把目标对准 80 端口和 8000 端口。

使用 netstat 查找端口占用者 (管理员权限) :
打开一个 管理员权限 的命令提示符（CMD）或 PowerShell。这一点很重要，普通用户权限可能看不到所有进程信息。
- 检查 80 端口：
```
netstat -ano | findstr ":80"
```
- 检查 8000 端口：
```
netstat -ano | findstr ":8000"
```
这个命令会列出所有活动的 TCP 连接，-a 显示所有连接和监听端口，-n 以数字形式显示地址和端口号，-o 显示拥有的进程标识符（PID）。findstr 用来过滤出包含指定端口号的行。

注意看输出结果最后一列的 PID。如果找到了占用 80 或 8000 端口的进程，记下它的 PID。
根据 PID 找到并终止进程 :
- 方法一：任务管理器
  按 Ctrl+Shift+Esc 打开任务管理器，切换到 “详细信息” (Details) 标签页。找到对应 PID 的进程，右键点击，选择 “结束任务” (End task)。
- 方法二：命令行 (管理员权限)
  在管理员命令提示符或 PowerShell 中运行：
```
taskkill /PID <你的PID> /F
```
  把 <你的PID> 替换成你找到的那个数字。/F 参数表示强制终止。
常见占用 80 端口的“嫌疑犯”：
- IIS (World Wide Web Publishing Service / W3SVC)
- SQL Server Reporting Services
- Skype (旧版本有时会占用 80)
- 其他 Web 服务器软件 (比如没完全卸载干净的 Apache)
- 某些 P2P 软件
注意安全： 结束进程前，最好确认一下它是什么。如果是重要的系统服务，随意结束可能导致系统不稳定。如果是你不认识的进程，可以先搜一下进程名了解它的作用。

干掉占用进程后，再试试启动 Herd 的 Nginx 或运行 php artisan serve。

方案二：提升权限，解决访问限制

Nginx 的 10013 错误直指权限问题，所以提升权限是关键一步。

以管理员身份运行 Laravel Herd :
找到 Laravel Herd 的快捷方式或可执行文件，右键点击，选择 “以管理员身份运行”。这样 Herd 启动的 Nginx 服务就有足够权限去绑定 80 端口了。
以管理员身份运行你的终端 :
同样，你用来执行 php artisan serve 命令的那个终端（比如 Windows Terminal, CMD, PowerShell, Git Bash 等），也需要以管理员身份启动。右键点击终端图标，选择 “以管理员身份运行”。

原理 : 这样操作赋予了 Nginx 和 PHP 进程更高的系统权限，让它们能够请求和绑定特权端口或绕过某些用户级别的访问限制。

安全建议 : 长期以管理员身份运行开发工具不是最佳实践，但对于本地开发调试端口问题是常用的解决手段。确保你的开发环境安全，不要随意运行来源不明的代码。

方案三：给 `php artisan serve` 换个端口

既然默认的 8000 和后续端口都用不了，干脆指定一个偏僻点、基本不可能被占用的端口。

指定端口运行 :
在你的项目根目录下，打开终端（建议还是用管理员权限打开，以防万一），运行：
```
php artisan serve --port=8888
```
你可以把 8888 换成任何你觉得合适的、大于 1024 的端口号，比如 9000, 9999 等。
检查新端口是否可用 (可选但推荐) :
在运行上面命令之前，可以用 netstat 再次确认你选的新端口（比如 8888）是真的空闲：
```
netstat -ano | findstr ":8888"
```
如果没有任何输出，说明这个端口目前没被占用，用它启动 artisan serve 的成功率会高很多。

原理 : 直接绕开有问题的端口范围，找一个干净的端口来用。这是解决端口冲突最直接有效的办法之一。

进阶技巧 : 虽然 artisan serve 不直接读取 .env 文件里的 APP_PORT 变量来设定端口，但你可以在 .env 里记下你常用的备选端口，或者在 package.json 的 scripts 里定义一个带端口的启动命令，方便以后使用，例如：
```
// package.json
"scripts": {
    "serve:dev": "php artisan serve --port=8888"
}
```
然后用 npm run serve:dev 或 yarn serve:dev 启动。

方案四：拥抱 Herd 的工作方式

Laravel Herd 的核心是替代 php artisan serve 这类临时开发服务器。它通过高性能的 Nginx (或 Caddy) 来直接服务你的项目，并提供更接近生产环境的体验（比如支持自定义域名 .test）。

停止尝试 php artisan serve : 如果你打算用 Herd，可能根本不需要手动运行 artisan serve。
确保 Herd 服务正常运行 : 打开 Herd 的界面，确认 Nginx (或 Caddy) 和 PHP 服务都是绿灯运行状态。如果 Nginx 无法启动（就是那个 80 端口的报错），那你需要先解决 80 端口的占用或权限问题（回到方案一和方案二）。
配置 Herd 管理你的项目 :
- Park : 把包含多个 Laravel 项目的父目录添加到 Herd 的 "Parked Paths" 中。Herd 会自动为该目录下的每个文件夹创建一个 foldername.test 的访问域名。
- Link : 如果你的项目不在 Parked 目录里，可以单独把它 "Link" 到 Herd。在 Herd 设置的 "Sites" 里，可以链接一个项目目录，并指定一个 .test 域名。
通过 Herd 分配的域名访问 : 配置好后，直接在浏览器访问 Herd 为你生成的 .test 域名（例如 my-awesome-project.test），而不是 127.0.0.1:8000。Herd 的 Nginx 会处理请求并将其转发给对应的 PHP-FPM 进程。

原理 : 切换思路，利用 Herd 提供的集成环境。这样就避免了 artisan serve 可能带来的端口冲突和管理问题。让 Herd 的 Nginx 监听 80/443 端口，统一处理所有项目的 Web 请求。

前提 : Herd 的核心服务必须能正常启动。如果 Nginx 因为 80 端口问题起不来，那么这个方案的前提就不成立，必须先解决 Nginx 的启动问题。

方案五：检查 Windows 端口排除范围 (较少见)

Windows 有个特性，可以预留某些 TCP 端口范围给系统功能（如 Hyper-V），导致这些端口即使没被程序监听，也无法被其他应用绑定。

查看排除的端口范围 (管理员权限) :
在管理员 PowerShell 中运行：
```
netsh interface ipv4 show excludedportrange protocol=tcp
```
这个命令会列出系统保留的 TCP 端口段。
检查是否包含 8000-8010 : 看看输出的范围列表里，有没有覆盖到 8000 到 8010 这个区间。

如果真的被排除了怎么办？
- 确认原因 : 通常和 Hyper-V 或者 Windows NAT (用于 WSL2 或 Docker Desktop) 有关。
- 尝试调整 : 禁用相关功能（如果你不需要它们）可能释放这些端口，但操作比较复杂且可能影响其他功能。或者通过 netsh 命令尝试修改排除范围（需要非常谨慎，可能需要重启）。
- 更简单的办法 : 还是用方案三，换个没被排除的端口。
注意 : 修改系统端口排除范围属于高级操作，一般不推荐，除非你非常清楚自己在做什么。优先考虑前面几个方案。

结合 Nginx 报的权限错误和 artisan serve 连续多个端口失败的情况，最可能的罪魁祸首是 权限问题 （影响 Nginx 绑定 80 端口）和/或 某个服务/系统特性隐藏地占用了 8000 附近的端口范围 ，或者是 Herd 环境自身的冲突 。

建议按顺序尝试：

用 管理员权限 运行 Herd 和你的终端。
用 netstat -ano 仔细查找并 终止占用 80 和 8000 端口的进程 。
如果只想用 artisan serve，指定一个高位端口 (--port=xxxx)。
如果打算完全拥抱 Herd，专注于让 Herd 的 Nginx 正常运行 （解决 80 端口问题），然后 通过 Herd 配置的 .test 域名访问项目 ，而不是运行 artisan serve。