LaravelValet使用教程：轻量开发环境指南

Laravel Valet 是一款专为 macOS 设计的极简本地开发环境，摒弃 Docker 和虚拟机，依托 dnsmasq 与 Nginx 实现 *.test 域名自动解析和请求转发，但其“轻量”背后隐藏着严格的环境前提——80 端口必须空闲、PHP 必须由 Homebrew 安装（≥8.1）且路径精准、valet park 与 link 的机制差异需厘清、PHP 版本切换需同步更新 Homebrew 软链、HTTPS 证书更需手动导入钥匙串并设为“始终信任”，任何一环疏忽都会引发 502、404 或证书警告等看似诡异实则必然的故障；这并非工具缺陷，而是对开发者环境意识与细节把控的隐性考验——越追求简洁，越要敬畏约定。

Valet 不是跨平台工具，只在 macOS 上能用；它不跑 Docker、不配虚拟机，靠 dnsmasq + nginx 做域名代理和请求转发，所有项目默认走 http://xxx.test —— 这个前提没搞清，后面全会卡住。

valet install 之前必须清理 80 端口和 PHP 环境

常见错误：执行 valet install 报错 “port 80 already in use” 或后续访问直接 502。这不是 Valet 问题，是本地环境冲突。

• 先停掉可能占 80 端口的服务：sudo lsof -i :80 查进程，sudo kill -9 [PID] 干掉 Apache/Nginx/其他 Web 服务
• PHP 必须由 Homebrew 安装且版本 ≥ 8.1：brew install php@8.2（推荐），别用系统自带 PHP 或手动编译版
• 确认 which php 返回路径是 /opt/homebrew/bin/php（Apple Silicon）或 /usr/local/bin/php（Intel），否则 valet 启动的 PHP 进程和你终端里跑的不是同一个
• 运行 php -m | grep -E '^(opcache|mbstring|curl)$'，缺模块就重装：brew reinstall php@8.2

valet park 和 valet link 的实际区别与选法

两者都让项目可被访问，但机制不同，误用会导致路由 404 或静态文件暴露。

• valet park 是“目录级注册”：进入父目录（如 ~/Sites），执行后该目录下所有含 public/index.php 或 server.php 的子目录自动映射为 dirname.test；适合管理多个小项目
• valet link myapp 是“项目级绑定”：在项目根目录执行，生成 myapp.test 域名；要求当前目录下有 public/，且不能嵌套在另一个 valet park 目录里，否则优先级混乱
• 如果项目用了 Laravel Sail 或自定义 nginx.conf，valet link 会忽略那些配置 —— Valet 只认自己的驱动逻辑
• 执行后访问 404？立刻检查：ls -la public/ 是否存在、index.php 是否可读、项目根目录是否真在 valet park 路径内

切换 PHP 版本时 valet use 不生效的根本原因

valet use php@8.2 显示 success，但 php -v 没变 —— 这不是 Valet bug，是 Homebrew symlink 没切干净。

• 必须先 brew unlink php@8.1（当前旧版），再 brew link --force php@8.2，最后 valet use php@8.2
• valet use 只改 Valet 内部记录，不碰系统 PATH 或 Homebrew 的软链；跳过 brew unlink 或漏掉 --force，就会出现“Valet 认为切了，系统没切”的状态
• 验证是否真正生效：which php、php -v、valet status 三者输出的 PHP 版本必须完全一致
• Laravel 项目中 phpinfo() 页面显示的版本也得匹配，否则 .env 里设了 APP_DEBUG=true 却报错，容易误判成框架问题

HTTPS 和证书信任必须手动做一次

Valet 默认启用 HTTPS，但系统钥匙串不会自动信任，导致浏览器报“不安全连接”或直接拦截。

• 首次安装后必须运行：valet secure（为当前项目启用 HTTPS）或 valet trust（全局信任 Valet 根证书）
• valet trust 本质是把 ~/.config/valet/CA/LaravelValetCASelfSigned.pem 导入钥匙串，并设为“始终信任”；只运行命令不够，还得去“钥匙串访问 → 系统 → Laravel Valet CA”双击，展开“信任”，选“始终信任”
• 换过 PHP 版本或重装 Valet 后，证书可能失效，需重复 valet unsecure && valet secure + valet trust
• 别指望浏览器自动更新证书信任状态 —— 关闭所有 Chrome/Firefox 窗口再重开，否则缓存的错误提示还在

最常被忽略的是 PHP 模块完整性与钥匙串的手动信任操作；前者导致路由层直接崩，后者让 HTTPS 形同虚设。Valet 的“轻量”建立在严格约定上，绕过任一环，便捷性就立刻反转成排查黑洞。

终于介绍完啦！小伙伴们，这篇关于《LaravelValet使用教程：轻量开发环境指南》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布文章相关知识，快来关注吧！