Laravel迁移中字段注释需自动转义单引号/反斜杠，MySQL 8.0+注释限1024字节且静默截断，须用Schema构建器+comment()链式调用、验证information_schema、统一UTF8MB4连接字符集。
迁移中给字段加注释时单引号、反斜杠直接报错
Laravel 的 comment() 方法底层走的是原生 SQL 的 COMMENT 子句，而 MySQL（尤其 5.7+）对注释字符串里的单引号、反斜杠、换行等字符极其敏感——不转义就会触发 SQL 语法错误，比如 SQLSTATE[42000]: Syntax error or access violation。
真正该做的不是“手动拼 SQL”，而是让 Laravel 自动处理字符串安全化。Laravel 9.2+ 内置了对 comment() 参数的自动转义，但前提是：你得用 DB::statement() 或原生 Schema 构建器，而不是靠手写字符串拼接。
- 别写
DB::statement("ALTER TABLE users COMMENT '用户表（含'管理员'角色）'")—— 单引号嵌套直接崩 - 改用 Schema 构建器 +
comment()链式调用，它会自动调用 PDO 的参数绑定逻辑做转义 - 如果必须动态拼注释（比如从配置读），先用
addcslashes($str, "'\")手动逃逸单引号和反斜杠
MySQL 8.0+ 注释长度超 1024 字节被截断却不报错
MySQL 对字段 COMMENT 的长度限制是 1024 字节（非字符数），中文 UTF8MB4 下一个汉字占 4 字节，256 个汉字就满了。更坑的是：超出部分静默截断，没有任何警告，migration 看似成功，但实际注释丢了后半截。
验证方式很简单：migration 执行完立刻查 information_schema.COLUMNS 表，别信 IDE 或 SHOW CREATE TABLE 的输出（它们有时缓存旧值）。
- 用
DB::select("SELECT COLUMN_COMMENT FROM information_schema.COLUMNS WHERE TABLE_NAME = ? AND COLUMN_NAME = ? AND TABLE_SCHEMA = ?", ['users', 'name', DB::getDatabaseName()])拿真实值 - 注释内容尽量精简，避免堆砌说明；如需长文档，改用数据库外的 README 或注释表
- CI 流程里可加断言：检查
mb_strlen($comment, 'UTF8MB4') * 4
使用 change() 修改字段并加注释时忘记加 doctrine/dbal
Laravel 默认不支持 change() 操作字段注释，因为底层依赖 Doctrine DBAL 解析表结构。没装这个包，执行 php artisan migrate 会直接抛出 DoctrineDBALDriverPDOException 或更隐蔽的 Unknown database type enum requested 错误。
这不是 Laravel 的 bug，是设计使然：原生 PDO 不提供跨库的字段元数据修改能力。
- 运行
composer require doctrine/dbal（Laravel 9+ 推荐 3.x 版本） - 确保 migration 中用了
table->string('status')->comment('状态')->change()这种链式写法，而不是先dropColumn再addColumn - 注意 DBAL 3.x 不兼容 SQLite，本地测试若用 SQLite，注释操作会被跳过且无提示
生产环境执行带注释的迁移后，Navicat / DBeaver 显示乱码
不是注释没写进去，而是客户端连接字符集没对齐。即使 Laravel 的 DB_CONNECTION 配置了 charset => 'utf8mb4'，MySQL 服务端默认连接仍可能用 latin1，导致注释存进去是 UTF8MB4 字节，但客户端按 latin1 解码就成 。
最稳的办法是统一在连接层强制指定：
- 在
config/database.php的 MySQL 配置里加'options' => [PDO::MYSQL_ATTR_INIT_COMMAND => "SET NAMES utf8mb4 COLLATE utf8mb4_unicode_ci"] - 确认 MySQL 服务端
my.cnf有collation-server = utf8mb4_unicode_ci和init-connect='SET NAMES utf8mb4' - 执行完 migration 后，连上数据库跑
SHOW VARIABLES LIKE 'character_set%';，重点看character_set_client和character_set_connection是否为utf8mb4
注释这事看着小，但一旦混入特殊字符、跨环境、跨客户端，排查链路极长。真正卡点往往不在 Laravel 代码里，而在 PDO 连接参数、MySQL 全局变量、甚至客户端工具自身的编码缓存。
