valet 是仅限 macos 的轻量开发环境，不依赖 docker 或虚拟机，通过 dnsmasq 和 nginx 实现 *.test 域名自动解析与请求转发；安装前须确保 80 端口空闲、php 由 homebrew 安装（≥8.1）且路径正确，否则将出现 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 的“轻量”建立在严格约定上，绕过任一环，便捷性就立刻反转成排查黑洞。
