PAYATHON 2026

如何从零创建 Laravel 项目并逐步安装 Laravel Breeze?

数据小陈

依次创建 Laravel 项目、配置数据库、安装 Breeze、执行迁移并启动应用。Breeze 会生成身份认证所需的路由、控制器和页面;完成数据库迁移并编译前端资源后,才能正常使用注册和登录功能。

下面以 Laravel 12、Breeze 2.x、Blade 和 SQLite 为例。原问题没有指定版本,这里固定 Laravel 主版本,方便按步骤操作。Breeze 2.x 的依赖声明包含 Laravel 12 对应的 Illuminate 组件;使用其他版本时,请先确认依赖兼容性。Breeze 依赖声明

1. 准备开发环境

需要安装 PHP、Composer,以及满足前端依赖要求的 Node.js 和 npm。示例使用 SQLite,因此 PHP 还需要启用 pdo_sqlite 扩展,无需单独启动数据库服务。

先检查命令是否可用:

php -v
composer --version
node -v
npm -v
php -m

PHP 及扩展的具体要求以所安装项目的 composer.json 和 Composer 提示为准。如果提示缺少扩展或版本不兼容,先解决环境问题,再继续操作。Laravel 安装文档

2. 创建 Laravel 项目

在准备存放项目的目录中执行:

composer create-project laravel/laravel breeze-demo "^12.0"
cd breeze-demo
php artisan --version

breeze-demo 是示例目录名,可以自行替换。后面的命令都在项目根目录执行。

正常安装后,项目会包含 .env 文件。如果该文件不存在,将 .env.example 复制为 .env。只有新项目的 APP_KEY 为空时,才需要执行:

php artisan key:generate

3. 配置 SQLite 数据库

编辑项目根目录的 .env,确认以下配置:

APP_URL=http://127.0.0.1:8000
DB_CONNECTION=sqlite

如果存在 DB_URL 或 DB_DATABASE,删除或注释它们,避免旧配置覆盖连接信息。这里使用 Laravel 默认的 database/database.sqlite 路径。

确保数据库文件存在。下面的命令只会在文件不存在时创建,不会清空已有文件:

php -r "file_exists('database/database.sqlite') || touch('database/database.sqlite');"
php artisan config:clear

Laravel 新项目可能已经创建了 SQLite 文件并执行过初始迁移,这是正常情况。后续继续执行 migrate 即可。Laravel 数据库初始化说明

4. 安装 Laravel Breeze

先安装 Breeze 包,再生成认证代码:

composer require laravel/breeze:"^2.0" --dev
php artisan breeze:install

在交互选项中选择 Blade 前端栈,测试框架按需要选择。其余可选功能可以先使用默认选项。

其中,composer require 安装生成器,breeze:install 将认证相关代码生成到项目中。只安装 Composer 包,还不能直接访问完整的登录页面。Breeze 安装说明

5. 执行迁移并安装前端依赖

运行:

php artisan migrate
npm install

migrate 会执行尚未执行的数据库迁移,创建用户表等应用所需的数据表;npm install 安装前端依赖。如果 Breeze 安装过程已经完成前端依赖安装,可以跳过重复安装。

可以检查迁移状态:

php artisan migrate:status

如果提示没有待执行的迁移,通常表示相关迁移已经完成,无需重新建表。

6. 启动应用和前端开发服务

打开两个终端,分别进入项目根目录。

终端一启动 Laravel:

php artisan serve --host=127.0.0.1 --port=8000

终端二启动 Vite:

npm run dev

保持两个进程运行,然后在浏览器访问:

  • 注册页面:http://127.0.0.1:8000/register
  • 登录页面:http://127.0.0.1:8000/login

Laravel 服务处理页面请求,Vite 提供开发时的 CSS 和 JavaScript 资源。浏览器应访问 Laravel 的地址。Breeze 页面与资源编译说明

7. 验证注册和登录

在 /register 创建一个测试账号,确认能够进入登录后的页面;退出后,再通过 /login 使用同一账号登录。

还可以检查认证路由是否已经生成:

php artisan route:list --path=register
php artisan route:list --path=login

需要在你的环境中实际执行这些检查,安装命令本身不能证明注册和登录已经成功。

常见问题如何处理?

  • 出现 could not find driver:检查命令行 PHP 是否启用了 pdo_sqlite。终端使用的 PHP 可能与其他开发工具使用的 PHP 不同。
  • 提示数据库表不存在:确认 .env 指向预期数据库,执行 php artisan config:clear 后再运行 php artisan migrate。
  • 提示 Vite manifest not found 或页面缺少样式:先确认 npm install 成功,再运行并保持 npm run dev。如果不需要开发时热更新,可以执行 npm run build 生成静态资源。
  • /login 或 /register 返回 404:确认已执行 php artisan breeze:install,并检查 routes/auth.php 是否存在、是否由 routes/web.php 引入。
  • Composer 或 npm 报版本冲突:根据错误信息调整 PHP、Node.js 或依赖版本,不要通过忽略平台要求来跳过兼容性检查。

以上步骤用于本地开发。密码重置邮件还需要单独配置邮件发送服务;能打开登录页面并不代表邮件功能已经可用。

备注:内容仅供参考。