跳转到主要内容

VillageSQL is a drop-in replacement for MySQL with extensions.

All examples on this page work on VillageSQL. Install Now →
新建的 Laravel 12 项目在 .env 中自带一个被注释掉的 MySQL 连接块,就位于当前生效的 DB_CONNECTION 行的正下方,使用的是每个 MySQL 客户端都熟悉的主机、端口、数据库、用户名和密码这一套形式。取消注释并填入真实值,就是全部的集成工作。本指南从头到尾讲解这个设置:连接、运行迁移,以及通过 Eloquent 读写。

创建项目

这会安装 Laravel 12 及其依赖,生成应用密钥,并创建一个默认的 SQLite 数据库,使应用无需任何配置即可立即运行。确认版本:
Laravel 12 需要 PHP 8.2 或更高版本。在尚未安装 PHP 的 macOS 上,brew install php composer 会同时安装两者;Homebrew 构建的 PHP 8.5 默认包含 pdo_mysql 和 mysqli,所以 MySQL 不需要额外的扩展设置。

创建数据库和用户

创建一个专用数据库和一个范围受限的用户,而不是把应用指向 root:

配置连接

打开 .env,把 DB_CONNECTION 从 sqlite 改为 mysql,然后填入连接细节:
这里 Laravel 通过 TCP 连接到 127.0.0.1,也就是上面 CREATE USER 语句授权的那个主机。VillageSQL 是 MySQL 的直接替代品,所以 config/database.php 和 .env 中的键都不需要改动。 config/database.php 默认在 mysql 连接上设置了 'strict' => true。这会让会话进入 MySQL 的标准严格 SQL 模式:
这组模式在 VillageSQL 上原样运行。没有任何严格模式标志需要为兼容性而禁用或绕过。

运行迁移

Laravel 的默认迁移会创建 users、cache 和 jobs 表。针对已配置的连接运行它们:
为 posts 表生成一个模型及其迁移:
在生成的迁移中添加 title 和 body 列:
运行它,然后直接在服务器上确认表的结构:

Eloquent 与批量赋值保护

Laravel 的 Eloquent 模型默认阻止批量赋值,除非字段列在 $fillable 中:
id、created_at 和 updated_at 被有意排除在外。向 create() 传入 id 不会报错,也不会覆盖值;Eloquent 会静默丢弃任何不在 $fillable 中的键:
该行得到的是下一个自增值,而不是 999。当 store() 方法直接接受请求体时,这一点很重要:如果没有 $fillable 限定列,客户端可以传入 id 或时间戳字段,并被照单全收。$fillable 保护模型;请求验证是另一个独立的关注点,它检查传入数据的形态。

路由和控制器

Laravel 12 的默认骨架把路由保持得很精简:routes/web.php 存放路由,bootstrap/app.php 负责接入中间件和异常处理,不再有旧的 Http/Kernel.php 文件。生成一个控制器:
注册路由:
routes/web.php 运行在 Laravel 基于会话的 CSRF 中间件之后,该中间件会以 419 Page Expired 拒绝一个普通的 curl -X POST,因为请求没有携带 CSRF 令牌。对于面向浏览器的表单路由,这是符合预期的;真实的表单通过隐藏字段提交令牌。对于打算被直接调用、没有表单也没有令牌的路由,请在 bootstrap/app.php 中把它排除:

端到端验证

启动内置服务器并测试两个路由。表中已经有了上面 $fillable 演示中的那一行,所以 index 路由会返回它:
直接查询数据库来确认两行都已落库,而不是只相信 JSON 响应:

常见问题

为什么 Laravel 默认使用 SQLite 而不是 MySQL?

近期的 Laravel 版本让新项目默认使用 SQLite,这样 php artisan serve 无需任何配置即可立即运行。.env 文件仍然在当前生效的 DB_CONNECTION 行正下方保留着 MySQL 连接键,只是被注释掉了。切换到 MySQL 只是取消注释并填入五个值,而不是新增一个配置段。

Eloquent 需要任何特殊配置才能与 VillageSQL 配合吗?

不需要。VillageSQL 是 MySQL 的直接替代品,使用同样的线路协议,所以 Laravel 的 mysql 驱动、它的严格 SQL 模式设置以及它的查询语法都可以原样运行。

$fillable 和请求验证有什么区别?

$request->validate() 决定从传入请求中接受哪些字段,并以 422 响应拒绝格式错误的输入。模型上的 $fillable 决定您传给 create() 或 fill() 的字段中有哪些会被真正写入数据库。只使用 $request->validate() 时,如果别处的某个控制器调用了 Post::create($request->all()),模型仍然暴露在批量赋值之下;而 $fillable 无论哪个控制器调用都会保护模型。

故障排除

另请参阅