如何配置MacOS运行Laravel项目 Mac上搭建Laravel PHP环境指南

在 macos 上配置并运行 laravel 项目，核心在于使用 laravel valet 搭建轻量高效的本地开发环境。1. 安装 xcode command line tools；2. 安装 homebrew；3. 使用 homebrew 安装 php；4. 安装 composer；5. 安装 mysql 或其他数据库；6. 安装 laravel valet；7. 创建 laravel 项目；8. 配置 .env 文件；9. 运行迁移；10. 通过 valet 访问项目。valet 简化了 nginx 和 dns 配置，支持 https，且资源占用低，适合大多数 laravel 本地开发需求。不同 php 版本可通过 valet 的 valet use 命令按项目切换。常见问题包括 path 配置、文件权限、数据库连接、composer 内存限制和 valet 域名解析等，均可通过对应命令和配置解决。

在 macOS 上配置并运行 Laravel 项目，核心在于搭建一个稳定且高效的 PHP 开发环境。这通常涉及到安装 Homebrew、PHP、Composer，然后选择一个本地服务器解决方案，如 Laravel Valet，最后创建并配置你的 Laravel 项目。

解决方案

要在 Mac 上搭建 Laravel 开发环境，我通常会遵循以下步骤，这套流程下来，基本上能应对绝大多数的本地开发需求：

首先，确保你的系统已经安装了 Xcode Command Line Tools，这是很多开发工具的基础。在终端运行 xcode-select --install 就可以搞定。

立即学习“PHP免费学习笔记（深入）”；

1. 安装 Homebrew Homebrew 是 macOS 上不可或缺的包管理器，它能极大简化后续 PHP、Composer 等工具的安装。

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后，记得按照终端提示配置环境变量，确保 brew 命令可用。

2. 安装 PHP 通过 Homebrew 安装 PHP 是最省心的办法。我个人偏好使用最新的稳定版，比如 PHP 8.2 或 8.3。

brew install php@8.2 # 或者你需要的其他版本

安装后，Homebrew 会自动为你处理好 PATH，但偶尔也需要手动检查一下 echo $PATH，确保 Homebrew 的 PHP 路径在系统默认 PHP 路径之前。

3. 安装 Composer Composer 是 PHP 的依赖管理工具，Laravel 项目的基石。

brew install composer

安装完成后，你可以通过 composer --version 验证是否安装成功。

4. 安装数据库 (可选但推荐) Laravel 项目通常需要数据库。MySQL 是一个常见的选择。

brew install mysql
brew services start mysql # 启动 MySQL 服务

你也可以选择 PostgreSQL 或 SQLite。SQLite 甚至不需要额外安装，直接在项目 .env 文件中配置即可。

5. 安装 Laravel Valet 这是 macOS 上我最推荐的本地开发服务器方案。它轻量、快速，而且配置简单到令人发指。

composer global require laravel/valet
valet install

valet install 会安装 Nginx 和 DnsMasq，并将其配置为在后台运行。

6. 创建 Laravel 项目 现在，你可以创建一个新的 Laravel 项目了。有两种常用方式：

• 通过 Laravel Installer:

  composer global require laravel/installer
  laravel new my-project # 创建一个名为 my-project 的新项目

• 通过 Composer 直接创建:

  composer create-project laravel/laravel my-project

  进入项目目录：cd my-project

7. 配置项目与 Valet 进入你新创建的 Laravel 项目目录，然后运行：

valet park # 如果你希望 Valet 自动为你目录下的所有项目提供服务
# 或者
valet link # 如果你只想为当前项目创建一个特定域名

valet park 会让 Valet 监控你当前所在的父目录（比如 ~/Sites），所有子目录下的 Laravel 项目都会自动获得一个 .test 域名（例如 my-project.test）。valet link 则为当前目录创建一个符号链接，并生成一个域名。我个人更喜欢 valet park，因为我所有的项目都放在一个统一的 ~/Sites 目录下。

8. 配置 .env 文件 复制 .env.example 到 .env：

cp .env.example .env

然后编辑 .env 文件，主要配置数据库连接信息。例如，如果你用了 MySQL：

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=my_project_db
DB_USERNAME=root
DB_PASSWORD=

记得在 MySQL 中创建对应的数据库 my_project_db。

9. 运行迁移

php artisan migrate

这将根据你的迁移文件在数据库中创建表结构。

10. 访问项目 现在，你可以在浏览器中访问 my-project.test (或者你 Valet 配置的域名) 来查看你的 Laravel 应用了。

为什么选择 Laravel Valet 而不是传统的 Nginx/Apache + PHP-FPM 组合？

说实话，对于 macOS 上的 Laravel 本地开发，我几乎是 Valet 的死忠粉。它简直就是为 Mac 用户量身定制的。

首先，极致的零配置。想想看，传统的 Nginx/Apache + PHP-FPM 组合，你需要安装 Nginx，配置虚拟主机，调整 PHP-FPM 的 sock 文件，处理权限问题，然后每次新增项目都要手动添加新的配置文件，再重启服务。这中间任何一步出错了，都可能让你浪费大量时间在排查上。Valet 呢？valet install，然后 valet park 或 valet link，搞定！它会自动帮你处理好 Nginx、DnsMasq 的配置，甚至连 SSL 证书都帮你自动生成（valet secure），让你的本地项目也能跑在 HTTPS 上，这对于很多需要安全上下文的开发来说简直是福音。

其次，轻量级与高性能。Valet 运行在后台，占用资源极少。它不像 Docker 或者 Vagrant 那样需要启动一个完整的虚拟机或容器，更不像 MAMP/XAMPP 那样集成了一堆你可能用不到的服务。Valt 仅仅是利用 Nginx 和 DnsMasq 来代理请求，非常高效。对于日常的 Laravel 开发，它的速度和响应能力绝对是顶级的。

Type

生成草稿，转换文本，获得写作帮助-等等。

下载

当然，如果你需要一个更接近生产环境的开发环境，或者项目涉及到复杂的微服务架构、需要特定的 Linux 环境，那 Docker 无疑是更好的选择。但对于绝大多数单一 Laravel 项目的本地开发，Valet 的便捷性和效率是无与伦比的。它让我能把更多精力放在代码本身，而不是环境配置上。

如何处理不同 Laravel 项目对 PHP 版本的要求？

这确实是个常见且让人头疼的问题。你可能手头有几个老项目跑在 PHP 7.4 上，新项目又必须用 PHP 8.2，甚至 8.3。在 macOS 上，有几种方法可以优雅地处理这个问题，我个人最常用的是结合 Homebrew 和 Valet 的特性。

Homebrew 允许你安装多个版本的 PHP。比如：

brew install php@7.4
brew install php@8.2
brew install php@8.3

安装后，Homebrew 会默认将最新的 PHP 版本链接到你的 PATH 中。如果你想切换全局的 PHP 版本，可以使用 brew link 和 brew unlink 命令，但这种方式比较麻烦，而且容易搞混。

更推荐的做法是利用 Laravel Valet 的版本切换功能。Valet 允许你为特定的项目或目录指定 PHP 版本。

• 为单个项目指定 PHP 版本： 进入你的项目目录，然后运行：

  valet use php@7.4 # 将当前项目切换到 PHP 7.4

  Valet 会自动配置 Nginx，让这个项目使用指定版本的 PHP-FPM。这个功能简直是多项目开发者的福音。

• 为所有项目或全局指定 PHP 版本： 如果你想让所有 Valet 服务的新项目都默认使用某个 PHP 版本，可以在任何地方运行：

  valet use php@8.2 # 将 Valet 的默认 PHP 版本切换到 8.2

除了 Valet，另一个更彻底的解决方案是使用 Docker。每个 Laravel 项目都可以拥有自己的 Dockerfile 和 docker-compose.yml 文件，完全隔离地运行在各自的容器中，拥有独立的 PHP 版本、数据库服务等。这种方式虽然初期配置成本稍高，但对于复杂的、需要高度隔离的项目来说，是终极解决方案。不过，对于仅仅是 PHP 版本切换的需求，Valet 已经足够简单高效了。

在 macOS 上搭建 Laravel 环境时常见的坑与解决方案

即便有 Valet 这样便捷的工具，在 macOS 上搭建 Laravel 环境时，还是会遇到一些“小插曲”。这些问题通常不复杂，但第一次遇到时可能让人摸不着头脑。

1. PATH 环境变量问题：

   • 坑： 安装 Homebrew 或 Composer 后，终端提示命令找不到（command not found）。这通常是 ~/.zshrc 或 ~/.bash_profile 文件中 PATH 变量没有正确配置。
   • 解法： 确保 Homebrew 的 bin 目录（/usr/local/bin 或 /opt/homebrew/bin）和 Composer 的全局 bin 目录（~/.composer/vendor/bin）在你的 PATH 中。比如，在 ~/.zshrc 中添加：

     export PATH="/opt/homebrew/bin:$PATH" # For Apple Silicon
     export PATH="$HOME/.composer/vendor/bin:$PATH"

     然后 source ~/.zshrc 或重启终端。

2. 文件权限问题：

   • 坑： Laravel 项目在运行时报错，提示 storage 或 bootstrap/cache 目录不可写。
   • 解法： 这是经典的权限问题。Laravel 需要对这两个目录有写入权限。在项目根目录运行：

     chmod -R 775 storage bootstrap/cache
     sudo chown -R $(whoami):staff storage bootstrap/cache

     $(whoami) 会自动替换为你的当前用户名。staff 是 macOS 上的默认用户组。

3. 数据库连接问题：

   • 坑： SQLSTATE[HY000] [2002] No such file or directory 或 Connection refused。
   • 解法： 这通常是数据库配置问题。
     • MySQL Socket 问题： macOS 上 Homebrew 安装的 MySQL 默认使用 socket 连接，但 PHP 有时找不到 socket 文件。在 .env 中，尝试将 DB_HOST 设置为 127.0.0.1 而不是 localhost，或者明确指定 socket 路径：

       DB_HOST=127.0.0.1
       # 或者
       DB_SOCKET=/tmp/mysql.sock # 检查你的 MySQL 实际 socket 路径，通常在 /tmp 或 /var/mysql

     • 服务未启动： 确保你的数据库服务（如 MySQL）正在运行：brew services start mysql。
     • 用户名/密码错误： 检查 .env 中的 DB_USERNAME 和 DB_PASSWORD 是否与你的数据库用户匹配。

4. Composer 内存限制：

   • 坑： 在运行 composer install 或 composer update 时，遇到 Allowed memory size of X bytes exhausted 错误。
   • 解法： 增加 PHP 的内存限制。你可以临时在命令行中设置：

     php -d memory_limit=-1 $(which composer) install

     或者修改你的 php.ini 文件，找到 memory_limit 选项并增加其值，例如 memory_limit = 512M 或 memory_limit = -1 (无限制，不推荐在生产环境使用)。

5. Valet 域名解析或端口冲突：

   • 坑： *.test 域名无法访问，或者 Valet 无法启动。
   • 解法：
     • Valet 医生： 运行 valet doctor，它会诊断常见问题并给出建议。
     • 重启 Valet： valet restart 尝试重启 Valet 服务。
     • 端口冲突： 检查是否有其他服务占用了 80 或 443 端口。你可以用 sudo lsof -i :80 或 sudo lsof -i :443 来查看。如果 Valet 无法启动，可能是 DnsMasq 或 Nginx 配置有问题，可以尝试 valet uninstall 后再 valet install 重新安装。

这些“坑”往往是初学者最容易卡住的地方，但一旦你了解了背后的原因和解决方案，它们就变得微不足道了。总的来说，在 macOS 上搭建 Laravel 环境，虽然偶尔有些小波折，但 Laravel Valet 的出现，已经让整个过程变得异常顺畅和愉快。