最稳方式是用 composer create-project --prefer-dist laravel/lumen myapi，不依赖全局环境；需手动初始化 .env 并生成 APP_KEY；默认不加载 routes/web.php，须在 bootstrap/app.php 中显式引入；启用 Eloquent 前需确认 PDO 扩展已开启。
直接用 composer create-project 最稳，别碰 lumen new（除非你配好了全局路径）
现在最可靠、兼容性最好的方式就是通过 Composer 直接拉取官方包。虽然文档提过 lumen new 命令，但它依赖全局安装的 laravel/lumen-installer，而这个 installer 在 PHP 8+ 和较新 Composer 版本（v2.5+）下已多年未更新，容易报 Class 'Laravel\Lumen\Console\LumenApplication' not found 或命令根本不可用。
-
composer create-project --prefer-dist laravel/lumen myapi是默认推荐，不依赖全局环境，项目自带完整依赖 - 加
--prefer-dist能跳过 Git 克隆，下载预编译 zip 包，快且干净 - 如果想装旧版本（比如适配 PHP 7.4 的 Lumen 8.x），可加版本约束：
composer create-project --prefer-dist laravel/lumen myapi "8.3.*" - 别用
composer create-project laravel/lumen不带版本——它默认拉最新版（目前是 Lumen 10.x），但要求 PHP >= 8.1，老项目容易翻车
.env 文件必须手动初始化，APP_KEY 不生成就别跑起来
Lumen 启动时不会自动创建 .env，也不会校验 APP_KEY 是否合法。没这一步，所有加密操作（如 session、JWT 签名）都会静默失败，接口返回空或 500 却查不到原因。
- 先复制模板：
cp .env.example .env - 立刻生成密钥：
php artisan key:generate—— 这条命令会往.env里写入 32 字符的APP_KEY - 检查生成结果：
grep APP_KEY .env，确保值形如APP_KEY=base64:abcd...xyz=，不是SomeRandomKey...这种占位符 - 如果用 Docker 或 CI 环境，别把
.env提交进 Git；用APP_KEY等变量走环境注入，但本地开发必须先有真实.env
路由文件默认是空的，routes/web.php 不加载就等于没接口
Lumen 默认禁用 Web 路由（和 Laravel 不同），routes/web.php 文件存在但不会被自动引入。如果你照着 Laravel 教程往里面写 $router->get(...)，请求会直接 404，连日志都不打。
- 打开
bootstrap/app.php，找到// $app->router->group(...)附近，取消注释这一行：$app->router->group(['namespace' => 'App\Http\Controllers'], function ($router) { require __DIR__.'/../routes/web.php'; }); - 或者更简单：在
bootstrap/app.php底部加一行require __DIR__.'/../routes/web.php';（适合纯 API 场景） - 验证是否生效：在
routes/web.php里写个测试路由$router->get('/ping', function () { return 'ok'; });，然后php -S localhost:8000 -t public访问/ping - 注意：Lumen 没有
routes/api.php，所有 API 都走web.php，别白找
开启 Eloquent 前先确认数据库扩展已启用，否则 Call to undefined method 错误不报具体原因
默认 Lumen 关闭了 Eloquent，启用只需一行 $app->withEloquent();，但很多人卡在 PDO 扩展没开，错误提示却是模糊的 Call to undefined method Illuminate\Database\Query\Builder::from() 或直接 500。
- 先运行
php -m | grep -i pdo，确保输出含pdo、pdo_mysql（或pdo_pgsql） - 再检查
.env中DB_CONNECTION是否拼错（常见写成mysql但实际要mysql，大小写敏感） -
$app->withEloquent();必须放在bootstrap/app.php中$app = new Laravel\Lumen\Application(...)之后、return $app;之前 - 模型里别用
protected $fillable = [...]就完事——Lumen 默认不启用批量赋值防护，得手动加use Illuminate\Database\Eloquent\Model;并继承它
bootstrap/app.php 和 .env，比查半天报错有用得多。 
