如何使用Laravel框架的Valet实现轻量级开发环境搭建？

本文共计1158个文字，预计阅读时间需要5分钟。

Valet 是一款专为 macOS 设计的本地开发工具，它不是跨平台工具，只能在 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 的“轻量”建立在严格约定上，绕过任一环，便捷性就立刻反转成排查黑洞。