Laravel Artisan 命令全解：按用途整理的 124 条命令手册

Artisan 是 Laravel 自带的命令行入口，执行 php artisan list 能看到当前项目里所有可用命令。这份清单不是固定的：安装的扩展包会追加命令，项目自己写的命令也会出现在里面。本文以 Laravel 13.32 为例，把本项目的 124 条命令按用途分组，顺手记下常用参数和踩过的坑。

先学会查，再谈背

命令数量每升级一次大版本都会变，与其背清单，不如记住下面四条：

php artisan list                 # 按命名空间分组列出全部命令
php artisan list --raw           # 一行一条，方便配合 grep / findstr 过滤
php artisan help make:model      # 查看某个命令的参数与选项（等价于 --help）
php artisan about                # 一次性看到环境、缓存、驱动、数据库连接

排查线上问题时，php artisan about 往往比翻 .env 更快：它会明确告诉你配置、路由、视图、事件是否已缓存，以及当前生效的缓存驱动和队列驱动。

全局选项

项目、配置与运行

维护模式有几个实用参数：

php artisan down --secret="molly2026" --retry=60 --render="errors::503"
php artisan up

--secret 会生成一个带令牌的访问地址，自己可以用它绕过维护页；--retry 告诉浏览器 60 秒后再试，避免用户反复刷新。

代码生成：make 家族

make:model 的短选项最值得记，一次能带出四五个文件：

php artisan make:model Article -mfsc
# -m 迁移  -f 工厂  -s 填充器  -c 控制器
# 需要资源控制器再加 -r，需要软删除加 -R

几个容易忽略的细节：make:controller --resource 生成七个方法骨架；--api 只保留增删改查接口需要的五个；make:test --pest 生成 Pest 风格测试；同名文件已存在时默认会提示，脚本里加 --force 才覆盖，慎用。

数据库与迁移

php artisan migrate --pretend      # 只打印将要执行的 SQL
php artisan migrate --force        # 生产环境必须显式加，防止误操作
php artisan migrate:rollback --step=1
php artisan db:seed --class=TechPostSeeder --force

--pretend 是上线前最该养成的习惯：把 SQL 看一遍再执行，比回滚数据库便宜得多。另外 schema:dump 之后，migrate 会先导入导出的结构与数据快照，只执行快照之后的迁移，冷启动测试会快很多。

路由、视图、事件与缓存

这里有两个经典问题。第一，config:cache 之后 env() 在 config 目录之外会返回 null，所有环境变量都应该经过配置文件再取。第二，route:cache 不接受闭包路由，执行时直接报错，路由统一写成控制器方法就没有这个约束。

队列

php artisan queue:work redis --queue=high,default --tries=3 --timeout=60 --sleep=3
php artisan queue:work --stop-when-empty --max-jobs=500
php artisan queue:restart

参数里最容易出错的是 --timeout：它必须小于队列配置的 retry_after，否则任务执行超时后会被重新投递，同一个任务跑两遍。生产环境用 Supervisor 或 systemd 托管 worker，不要挂在 nohup 里。

任务调度

线上只配一条 cron：

* * * * * cd /var/www/xml_blog && php artisan schedule:run >> /dev/null 2>&1

本地开发不要配 cron，直接 php artisan schedule:work 常驻即可。任务「该跑却没跑」时，先 schedule:list 确认时间表达式，再 schedule:clear-cache 清掉可能残留的互斥锁。

存储、发布与语言文件

调试、测试与运维

项目自己的命令

本站在框架命令之外还有两条自定义命令：blog:seed 写入内置文章，hot:fetch 采集各平台热榜。写一条自己的命令只要三步：

php artisan make:command HotFetch

# 生成的类里填上签名与说明
protected $signature = 'hot:fetch {platform?} {--limit=20}';
protected $description = '采集各平台热榜并写入数据库';

public function handle(): int
{
    $this->info('开始采集');

    return self::SUCCESS;
}

签名中的花括号是参数：{platform?} 为可选参数，{--limit=20} 为带默认值的选项。命令类放在 app/Console/Commands 会被自动注册，不需要改 Kernel。

生产环境别乱敲的命令

一个稳妥的上线顺序：拉代码 → composer install --no-dev → php artisan migrate --force → php artisan optimize → php artisan queue:restart → 检查 php artisan about 的缓存状态。

日常最常用的十条

1. php artisan list：找命令，永远从这条开始
2. php artisan make:model X -mfsc：一次生成模型、迁移、工厂、填充器、控制器
3. php artisan migrate --pretend：执行前先看 SQL
4. php artisan migrate:status：确认哪条迁移没跑
5. php artisan db:seed --class=XxxSeeder：按需补数据
6. php artisan route:list --path=admin：路由对不上时先列出来
7. php artisan tinker --execute="..."：快速验证一段逻辑
8. php artisan queue:work + queue:restart：队列改动后的固定动作
9. php artisan schedule:list：确认计划任务到底有没有注册上
10. php artisan optimize / optimize:clear：性能异常时的第一反应

命令会随版本变化，本文清单来自 Laravel 13.32。升级框架后重新跑一次 php artisan list，比对着旧文章找不存在的命令更靠谱。