Hyperf 3.0 迁移建表失败主因是命名空间错误（应继承Hyperf\DbConnection\Migrations\Migration）、字段定义不兼容（如id()不可用，需用bigIncrements）、数据库未预创建或权限不足，而非迁移命令本身问题。
Hyperf 3.0 的迁移命令本身不报错，但创建表字段时失败，通常不是命令问题，而是迁移文件写法、数据库配置或组件兼容性出了偏差。重点不在“怎么运行”，而在“为什么 up() 执行 SQL 会失败”。
迁移类必须用正确的命名空间和继承关系
Hyperf 3.0 已移除 hyperf/database，改用 hyperf/db-connection。迁移类不再继承 Hyperf\Database\Migrations\Migration（该类已不存在），而应继承：
Hyperf\DbConnection\Migrations\Migration
同时确保 use 语句正确：
use Hyperf\DbConnection\Migrations\Migration; use Hyperf\DbConnection\Schema\Schema;
若仍用旧命名空间，运行 php bin/hyperf.php migrate 会直接抛 Class not found，而不是建表失败。
字段定义要匹配当前 Schema 构建器能力
Hyperf 3.0 的 Schema::create() 底层调用的是 Hyperf\DbConnection\Schema\Grammars\MySqlGrammar 等驱动语法生成器。常见字段报错场景：
-
$table->id()报错：确认是否用了bigIncrements('id')替代（id()是 Laravel 风格，在 Hyperf 3.0 中未默认提供） -
$table->json('data')在 MySQL 5.7 以下不支持：需显式加判断if ($this->schema->hasType('json')) { ... } -
$table->timestamps()报错：检查是否漏了use Illuminate\Support\Facades\DB;—— 不需要，Hyperf 不依赖 Illuminate；应直接用$table->dateTime('created_at')->nullable()等手动声明
执行前务必确认数据库已存在且权限足够
Hyperf 迁移不会自动创建数据库，也不会帮你建用户权限。常见报错如：
-
SQLSTATE[HY000] [1049] Unknown database 'xxx'：先手动执行CREATE DATABASE xxx CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; -
SQLSTATE[42000]: Syntax error or access violation：检查数据库用户是否有CREATE TABLE、INDEX、ALTER权限 -
Base table or view already exists：说明表已存在，可在up()开头加防护：if (! $this->schema->hasTable('users')) { Schema::create('users', function (Blueprint $table) { ... }); }
调试建议：先预览 SQL 再执行
加 --pretend 参数可跳过真实执行，只输出将要运行的 SQL：
php bin/hyperf.php migrate --pretend
对比输出的 SQL 是否符合目标数据库版本语法（例如 MySQL 8.0 支持 JSON 类型，但低版本需用 TEXT + 应用层处理）。也可复制 SQL 到数据库客户端中手动执行，快速定位是框架问题还是 DB 限制。
