Laravel 命令速查表 - Laravel Artisan 常用命令大全
这套速查给用 Laravel 做业务系统、以及负责部署的开发者，核心是每天都敲的 Artisan 命令行。它覆盖建项目、生成 controller/model/migration、跑与回滚迁移、用 route/config/view 缓存把线上性能提上去，以及用队列把重活丢到后台。与一条条堆 artisan 命令不同，条目按"建功能→迁库→本地联调→上线前缓存→队列化重活"的真实节奏排布。读完应能快速搭出一个 CRUD 功能并顺畅迁移库，同时心里清楚每一条缓存命令到底落地了什么、清了什么。
典型使用场景
面向日常在 Laravel 项目里做「生成骨架 → 跑迁移 → 接路由 → 起队列」这条流水线的后端工程师。Artisan 命令的价值在于它同时完成了建文件与注册约定：make:model -mcr 一次生成模型、迁移、控制器与资源控制器，省掉手工建文件和改文件名对应关系。本表覆盖项目与代码生成、数据库迁移与种子、路由与缓存、队列 worker、测试与调试、以及维护模式的上下线。真正需要理解的不是命令列表，而是三条约定：文件名决定类名、缓存类配置会锁住 env() 的运行时取值、队列进程要靠 queue:restart 才能加载新代码。
项目与开发 10
laravel new projectphp artisan servephp artisan make:model Post -mcrphp artisan make:migration create_posts_tablephp artisan make:controller PostControllerphp artisan make:middleware CheckAgephp artisan make:request StorePostRequestphp artisan make:job ProcessPodcastphp artisan make:event PodcastProcessedphp artisan make:listener SendNotification数据库 8
php artisan migratephp artisan migrate:freshphp artisan migrate:rollbackphp artisan migrate:statusphp artisan db:seedphp artisan db:seed --class=UserSeederphp artisan make:seeder UserSeederphp artisan make:factory PostFactory路由与缓存 9
php artisan route:listphp artisan route:cachephp artisan route:clearphp artisan config:cachephp artisan config:clearphp artisan view:cachephp artisan view:clearphp artisan optimizephp artisan optimize:clear队列与任务 7
php artisan queue:workphp artisan queue:work --queue=high,defaultphp artisan queue:restartphp artisan queue:failedphp artisan queue:retry <id>php artisan queue:flushphp artisan make:job ProcessPodcast测试与调试 6
php artisan testphp artisan test --filter=UserTestphp artisan tinkerphp artisan downphp artisan upphp artisan storage:link参数矩阵
| 参数 | 作用 | 示例 |
|---|---|---|
laravel new project | 创建新项目骨架（走 create-project 流程），比手工克隆模板更完整 | laravel new project |
php artisan serve | 启动内置开发服务器；这是开发服务器，不适合作为生产进程 | php artisan serve |
make:model Post -mcr | 一次生成模型（-m 迁移、-c 控制器、-r 资源控制器），是最高频的生成命令 | php artisan make:model Post -mcr |
make:migration create_posts_table | 只建迁移文件；命名必须是 create_xxx_table，否则回滚时找不到对应表 | php artisan make:migration create_posts_table |
make:controller PostController | 生成控制器；带 --invokable 可生成单动作控制器 | php artisan make:controller PostController |
make:middleware CheckAge | 生成中间件；注册到 Kernel 或 bootstrap 里的中间件栈才生效 | php artisan make:middleware CheckAge |
make:request StorePostRequest | 生成表单请求类，把校验与授权从控制器里分离出去 | php artisan make:request StorePostRequest |
make:job ProcessPodcast | 生成队列任务类；任务要能安全重试，不能假设只执行一次 | php artisan make:job ProcessPodcast |
make:event / make:listener | 生成事件与监听器，事件驱动解耦的标准组合 | php artisan make:listener SendNotification |
php artisan migrate | 执行未跑过的迁移；--force 可在生产跳过确认提示 | php artisan migrate |
php artisan migrate:fresh | 回滚全部并重建，会清空所有表数据；生产误用等同数据事故 | php artisan migrate:fresh |
php artisan migrate:rollback | 回滚最近一批迁移，常用于本地撤销刚写的迁移 | php artisan migrate:rollback |
php artisan migrate:status | 列出每个迁移是否已执行，排查「某张表没建出来」的第一步 | php artisan migrate:status |
php artisan db:seed --class=UserSeeder | 指定要跑的 Seeder 类；配合 --class 避免多个 seeder 时误跑 | php artisan db:seed --class=UserSeeder |
php artisan make:factory PostFactory | 生成模型工厂，测试里造假数据靠它，与 seeder 用途不同 | php artisan make:factory PostFactory |
php artisan route:list | 列出全部路由与中间件，排查 404 与中间件缺失的首选命令 | php artisan route:list |
php artisan route:cache | 缓存路由表，显著加速加载；路由文件里不能再有闭包路由 | php artisan route:cache |
php artisan config:cache | 缓存配置，之后 env() 在运行时取不到值（配置已固化成常量） | php artisan config:cache |
php artisan optimize | 一次性生成路由、配置与视图缓存，部署后的标准动作 | php artisan optimize |
php artisan optimize:clear | 清掉全部缓存；本地改了 .env 却没生效时先跑它 | php artisan optimize:clear |
php artisan view:cache / view:clear | 预编译视图 / 清除视图缓存，改了 blade 后没生效时清一次 | php artisan view:clear |
php artisan queue:work | 前台运行队列消费者，逐个处理任务；开发调试用这个能看到报错 | php artisan queue:work |
php artisan queue:work --queue=high,default | 指定队列优先级，按逗号顺序消费；配了高优队列却不写这个参数就会串行处理 | php artisan queue:work --queue=high,default |
php artisan queue:restart | 让运行中的 worker 优雅退出并在下次取任务时重启，是发布新代码的必要动作 | php artisan queue:restart |
php artisan queue:failed | 列出失败任务及其异常，排障入口 | php artisan queue:failed |
php artisan queue:retry <id> | 重试指定失败任务；也支持 flush 清空全部失败记录 | php artisan queue:retry <id> |
php artisan queue:flush | 清空所有失败任务记录，不可恢复；误用会丢掉排障线索 | php artisan queue:flush |
php artisan test | 运行测试套件；--filter 可只跑某个测试类 | php artisan test --filter=UserTest |
php artisan tinker | 进入带框架已启动的 REPL，用来验证模型、查询与关系是否如预期 | php artisan tinker |
php artisan down / up | 维护模式开关；down 会给所有请求返回 503，务必设 --retry 与 --secret | php artisan down |
php artisan storage:link | 创建 public/storage 符号链接；缺失时上传的图片无法通过 URL 访问 | php artisan storage:link |
易错点与避坑指南
现象改了 .env 里的配置，代码里读到的还是旧值。
原因配置被 config:cache 固化了，运行时不再解析 .env。
处置开发环境执行 php artisan optimize:clear；生产改配置后要重新执行 config:cache。
现象生产上部署了新代码，队列里跑的还是旧逻辑。
原因长期运行的 queue:work 进程已把代码载入内存，不会自动更新。
处置部署流程里执行 queue:restart 让 worker 优雅重启，并确认进程管理器会重新拉起。
现象route:cache 之后报 "Unable to prepare route ... uses Closure"，全部路由失效。
原因路由文件里有闭包路由，闭包无法被序列化进缓存。
处置把闭包路由改写成控制器类动作；开发环境用 route:clear 清掉缓存继续调试。
现象误在生产执行 migrate:fresh，表数据全没了。
原因fresh 会 drop 全部表再重建，没有确认也没有备份动作。
处置生产只允许 migrate；先备份数据库，并在流程上限制非交互环境使用 fresh。
现象上传的文件保存成功了，但访问 URL 返回 404。
原因public/storage 符号链接不存在，或共享主机不允许创建符号链接。
处置执行 storage:link；无法创建链接时改用 route 到一个控制器返回文件。
现象高优队列的任务迟迟不处理。
原因worker 启动时没带 --queue=high,default，或队列名在 dispatch 时与配置不一致。
处置按优先级顺序写全队列名，并核对 dispatch 使用的队列名与进程管理器里的启动参数。
现象make:migration 生成的文件名与表名不符，回滚时报找不到迁移。
原因手工命名没遵循框架约定的命名规则，或多次生成造成同批次回滚顺序错乱。
处置统一用 create_xxx_table / add_xxx_to_yyy_table 命名，并用 migrate:status 确认执行记录。
现象请求全部返回 503，忘记了自己开着维护模式。
原因php artisan down 之后的 up 未执行，异常时切进去的维护模式没退出。
处置执行 php artisan up；down 时带上 --retry=60 让客户端自动重试。
排障路径
1确认各迁移是否已执行
php artisan migrate:status「表不存在」类问题的第一步。
2查路由是否真的注册上
php artisan route:list404 时先确认路由存在，再看路径与方法是否匹配。
3清掉全部缓存
php artisan optimize:clear改了 .env、路由或视图后没生效时先跑它。
4让队列 worker 加载新代码
php artisan queue:restart发布新代码后的必要动作。
5查失败任务与异常信息
php artisan queue:failed先看异常类型再决定重试还是改代码。
6只跑单个测试类
php artisan test --filter=UserTest缩短反馈回路，同时确认测试环境配置正确。
命令示例
一条命令生成模型全套：迁移 + 控制器 + 请求类
php artisan make:model Post -mcr
php artisan make:request StorePostRequest
php artisan migrate-m 建迁移、-c 建控制器、-r 建表单请求，三件套生成后仍要手写字段、校验规则和授权逻辑。表单请求的价值在于校验失败自动回 302 带错误包，控制器里就不用重复写错误处理。
排查 404 / 405：先列出全部路由
php artisan route:list
php artisan route:list --path=posts
php artisan route:clear405 说明方法不匹配而路由存在（多半是前端发 POST、路由只写了 GET），404 才是路径或前缀不对。改过路由文件却仍走旧行为时，多半是 route:cache 缓存了旧表，先 clear 再验证。
改了 .env 却没生效：缓存全流程
php artisan config:clear
php artisan route:clear
php artisan view:clear
// 上线前反向烘焙
php artisan optimizeconfig:cache 会把 .env 的值烘焙进一个静态文件，此后改 .env 完全无效——这是「改了配置没反应」最常见的原因。改完 .env 必须 config:clear；上线前再用 optimize 一次性烘焙，把每请求读文件的开销省掉。
队列：按优先级消费 + 优雅重启
php artisan queue:work --queue=high,default
php artisan queue:restart
php artisan queue:failed
php artisan queue:retry <id>worker 是常驻进程，跑的是启动那一刻加载的代码；发布新版本后不重启，任务仍执行旧逻辑且没有任何提示——queue:restart 让 worker 处理完当前任务后自动退出重载。失败任务别急着 flush，先 queue:failed 看原因。
发布前后的迁移顺序：status 先行
php artisan migrate:status
php artisan migrate
php artisan migrate:rollback生产环境的迁移要「先发布兼容旧结构的代码、再执行迁移」，否则先加非空列会让仍在运行的旧版本写入直接失败。rollback 只回退最近一批，写错结构时比手工改表安全。migrate:fresh 会删库重建，只限开发与测试环境。
常见坑与注意事项
- php artisan config:cache 会把 .env 烘焙进静态缓存文件，之后改 .env 完全不生效，必须先 config:clear；不熟悉的「配置不生效」十有八九出在这里。
- php artisan migrate:fresh 会回滚全部迁移并重新执行，等于删库重建。在生产或任何含真实数据的库上执行会不可逆地丢数据，没有任何二次确认。
- 配置了 queue:work 常驻进程后发布新代码不重启，worker 仍按旧代码处理任务，行为与预期不一致且日志无提示；发布流程里必须带上 queue:restart。
- route:cache 缓存的是路由表，部署顺序不当（新代码 + 旧缓存）会让线上跑着一半新一半旧的控制器逻辑；线上加路由前先确认缓存是否已清。
- php artisan down 进入维护模式后忘记 php artisan up，站点会一直返回 503；异常退出维护模式前应确认 .env 中的 APP_ENV 与缓存状态已恢复。
- php artisan queue:flush 清空的是全部失败任务记录，出问题后先 queue:failed 留存原因再清，否则关键故障线索被一并删除。
提示
- 生产环境务必执行 php artisan optimize 缓存配置和路由。
- make:model -mcr 一次性生成模型+迁移+资源控制器，节省时间。
- 队列 worker 用 Supervisor 守护，避免进程意外退出。
常见问题
改了 .env 或路由后线上行为还是旧的，缓存要清哪些？
Laravel 把配置和路由都缓存成了文件，源码改了不生效就得按对应命令清。改完 .env 先 php artisan config:clear，再 php artisan route:clear 让路由重新解析；模板改动异常就 php artisan view:clear 清编译好的 blade。上线前用 php artisan optimize 一次烘焙配置与路由缓存以提升性能，回滚或恢复调试时用 php artisan optimize:clear 把全部缓存一并清空。改完配置缓存不生效是本地开发最常见的困惑来源。
改了迁移文件后悔了，怎么回到上一步或重建数据库？
分两级。php artisan migrate:rollback 回退最近一批迁移，适合迁移写错时撤回一步；php artisan migrate:fresh 先回滚全部再重跑一遍，等于重建全部表结构，开发和测试环境用它快速重置，但会清掉所有数据。排查为什么某张表没建出来时先看 php artisan migrate:status，它会列出每条迁移的 pending / ran 状态。开发阶段灌测试数据用 php artisan db:seed，只跑某一个用 php artisan db:seed --class=UserSeeder。
队列任务失败了，怎么定位原因并重试？
先看失败清单：php artisan queue:failed 会列出处理失败的任务及其原因，结合日志判断是业务异常还是超时。重试指定任务用 php artisan queue:retry <id>，修好逻辑后临时救场用。确认无需再重试后，php artisan queue:flush 清空所有失败任务记录。消费端按优先级跑：php artisan queue:work --queue=high,default 先处理 high 队列再退到 default，让重要任务先落地；发布新代码后用 php artisan queue:restart 让 worker 处理完当前任务后重启加载新代码，生产环境应由进程管理器守护。
make:model 的那些参数怎么组合最省事？
常用组合是 php artisan make:model Post -mcr：-m 生成迁移、-c 生成资源控制器、-r 生成请求类（Form Request），一条命令把模型加配套文件一次铺好。只要迁移就 php artisan make:migration create_posts_table；只要控制器用 php artisan make:controller PostController。校验逻辑单独拆出来更清晰时用 php artisan make:request StorePostRequest，权限或登录态拦截用 php artisan make:middleware CheckAge。异步与事件相关的骨架有 php artisan make:job ProcessPodcast、php artisan make:event PodcastProcessed、php artisan make:listener SendNotification，假数据用 php artisan make:factory PostFactory 配合 faker 批量生成模型数据。
接口返回 404 或 405，先用什么命令定位？
php artisan route:list 会列出应用全部路由及其对应的控制器方法，方法名对不上就是路由没注册或路径拼错；同一路径出现多条时后面注册的会覆盖前面的，表现为「改了路由还是旧行为」。405 说明路由存在但 HTTP 方法不匹配（比如该 POST 却发了 GET），在 route:list 里核对方法列即可。日常开发用 php artisan serve 起服务，交互式验证逻辑可以 php artisan tinker 进 REPL，只想跑某个测试则 php artisan test --filter=UserTest；维护窗口用 php artisan down / php artisan up 控制。
由 巧匠 维护
公开更新于 2026年7月21日，内容持续校对官方文档。