如何从零创建 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 或依赖版本,不要通过忽略平台要求来跳过兼容性检查。
以上步骤用于本地开发。密码重置邮件还需要单独配置邮件发送服务;能打开登录页面并不代表邮件功能已经可用。
备注:内容仅供参考。
