Artisan 控制台 - Knowledge of Laravel

什么是 Artisan

Artisan 是 Laravel 内置的命令行界面(CLI)工具。它以项目根目录下的 artisan 脚本形式存在，提供了大量用于提升开发和运维效率的命令。要查看可用命令列表，使用 list 命令。

php artisan list

要查看某个命令的使用方法，在前面加上 help。

php artisan help migrate

如果使用 Laravel Sail，请使用 sail artisan 代替 php artisan。命令将在 Docker 容器内执行。

./vendor/bin/sail artisan list

Tinker

Laravel Tinker 是一个 REPL 环境，可以在命令行中交互式操作 Eloquent 模型、Job、事件等整个应用程序。

php artisan tinker

启动后即可直接执行 PHP 代码。

// 获取用户并查看
>>> App\Models\User::find(1)
// 使用工厂创建记录
>>> App\Models\User::factory()->create()
// 直接调用服务类
>>> app(App\Services\OrderService::class)->process(1)

Tinker 会实际修改数据。在生产环境执行时请务必谨慎。它适合在本地或预发环境用于验证行为和调试。

自定义命令的创建

生成命令

使用 make:command 生成命令类的骨架。

php artisan make:command ImportProducts

生成的文件位于 app/Console/Commands/ImportProducts.php。

命令的基本结构

生成的命令类包含三个主要要素：$signature、$description 和 handle()。

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;

class ImportProducts extends Command
{
    /**
     * 命令名与参数、选项的定义
     */
    protected $signature = 'import:products';

    /**
     * 命令的说明（会显示在 php artisan list 中）
     */
    protected $description = '从 CSV 导入商品数据';

    /**
     * 命令的执行处理
     */
    public function handle(): void
    {
        $this->info('开始导入...');
        // 编写处理逻辑
        $this->info('已完成。');
    }
}

在 Laravel 13 中还可以使用基于 PHP 属性的写法。

use Illuminate\Console\Attributes\Description;
use Illuminate\Console\Attributes\Signature;

#[Signature('import:products')]
#[Description('从 CSV 导入商品数据')]
class ImportProducts extends Command
{
    public function handle(): void
    {
        // ...
    }
}

参数和选项的定义

在 $signature 中统一定义命令名、参数和选项。

protected $signature = 'import:products
                        {file : 要导入的 CSV 文件路径}
                        {--limit= : 要导入的最大条数}
                        {--dry-run : 实际不保存到 DB（用于确认）}';

写法	类型	说明
`{file}`	必需参数	省略会报错
`{file?}`	可选参数	省略时为 `null`
`{file=products.csv}`	带默认值的参数	省略时使用默认值
`{--queue}`	标志选项	指定为 `true`，省略为 `false`
`{--limit=}`	带值的选项	通过 `--limit=100` 传值
`{--limit=50}`	带默认值的选项	省略时为 `50`
`{--Q\|queue}`	带简写	也可以用 `-Q` 指定

获取参数和选项

在 handle() 方法内使用 argument() 和 option() 获取值。

public function handle(): void
{
    $file    = $this->argument('file');       // 获取参数
    $limit   = $this->option('limit');        // 获取选项
    $dryRun  = $this->option('dry-run');      // 标志选项(bool)

    $this->info("文件: {$file}");

    if ($dryRun) {
        $this->warn('干跑模式：将跳过对 DB 的保存');
    }
}

`input()` — 类型化访问器

使用 input() 方法可以以与 HTTP 请求相同的类型化访问器方式获取命令的参数或选项。

use App\Enums\ReportType;

public function handle(): void
{
    // 以 CommandInput 实例的形式获取参数、选项
    $from = $this->input()->date('from');
    $type = $this->input()->enum('type', ReportType::class);
    $limit = $this->input()->integer('limit');
}

如果只想获取特定名称的值，可直接传入名称（会从参数和选项中搜索）。

$queue = $this->input('queue', 'default');

相比 argument() 或 option() 返回字符串，input() 的类型化访问器会转换为合适的类型。在需要类型安全地处理日期、数字、枚举等时非常方便。

与用户的交互

消息的输出

提供了向控制台输出带颜色消息的方法。

$this->info('处理已成功完成');    // 绿色
$this->warn('此操作无法撤销');    // 黄色
$this->error('发生错误');       // 红色
$this->line('普通文本');             // 无颜色
$this->comment('补充信息');               // 浅灰

向用户提问

可以交互式地从用户接收输入。

// 文本输入
$name = $this->ask('请输入负责人姓名');

// 带默认值
$env = $this->ask('选择执行环境', 'production');

// 密码等敏感信息（输入不会显示在屏幕上）
$password = $this->secret('请输入 API 密钥');

// Yes/No 确认
if (! $this->confirm('是否导入到生产 DB？')) {
    $this->info('已取消。');
    return;
}

// 从选项中选择
$format = $this->choice('请选择输出格式', ['csv', 'json', 'xml'], 0);

进度条

在处理大量数据时可以直观地显示进度。

use App\Models\Product;

// 传入集合，自动显示进度条
$this->withProgressBar(Product::cursor(), function (Product $product) {
    $this->processProduct($product);
});

若需要手动细粒度控制，可以使用以下方式。

$total = Product::count();
$bar = $this->output->createProgressBar($total);
$bar->start();

Product::cursor()->each(function (Product $product) use ($bar) {
    $this->processProduct($product);
    $bar->advance();
});

$bar->finish();
$this->newLine();

实用场景

数据导入命令

从 CSV 文件导入商品数据的实用命令示例。

生成命令

php artisan make:command ImportProducts

实现命令

<?php

namespace App\Console\Commands;

use App\Models\Product;
use Illuminate\Console\Command;

class ImportProducts extends Command
{
    protected $signature = 'import:products
                            {file : CSV 文件的路径}
                            {--limit= : 要导入的最大条数}
                            {--dry-run : 仅确认（不保存到 DB）}';

    protected $description = '从 CSV 文件导入商品数据';

    public function handle(): void
    {
        $filePath = $this->argument('file');
        $limit    = $this->option('limit') ? (int) $this->option('limit') : null;
        $dryRun   = $this->option('dry-run');

        if (! file_exists($filePath)) {
            $this->error("找不到文件: {$filePath}");
            return;
        }

        // 使用 PHP 内置函数读取 CSV
        $handle = fopen($filePath, 'r');
        $headers = fgetcsv($handle); // 将第一行作为表头
        $rows = [];
        while (($row = fgetcsv($handle)) !== false) {
            $rows[] = array_combine($headers, $row);
            if ($limit !== null && count($rows) >= $limit) {
                break;
            }
        }
        fclose($handle);

        $count = 0;

        $this->withProgressBar($rows, function (array $row) use ($dryRun, &$count) {
            if (! $dryRun) {
                Product::updateOrCreate(
                    ['sku' => $row['sku']],
                    [
                        'name'  => $row['name'],
                        'price' => $row['price'],
                    ]
                );
            }
            $count++;
        });

        $this->newLine();

        if ($dryRun) {
            $this->warn("共 {$count} 条为目标（干跑模式：已跳过保存）");
        } else {
            $this->info("已完成 {$count} 条数据的导入。");
        }
    }
}

执行命令

# 常规导入
php artisan import:products storage/products.csv

# 限制条数
php artisan import:products storage/products.csv --limit=100

# 用干跑模式确认
php artisan import:products storage/products.csv --dry-run

定期维护命令

用于定期删除旧数据等的维护命令示例。

<?php

namespace App\Console\Commands;

use App\Models\Order;
use Illuminate\Console\Command;

class PruneOldOrders extends Command
{
    protected $signature = 'orders:prune {--days=90 : 删除多少天以前的数据}';

    protected $description = '删除指定天数以前的已完成订单';

    public function handle(): void
    {
        $days = (int) $this->option('days');

        if (! $this->confirm("是否删除 {$days} 天以上前的已完成订单？")) {
            $this->info('已取消。');
            return;
        }

        $deleted = Order::where('status', 'completed')
            ->where('created_at', '<', now()->subDays($days))
            ->delete();

        $this->info("已删除 {$deleted} 条订单数据。");
    }
}

与计划任务组合

创建的命令可以通过 routes/console.php 进行计划执行。详情请参阅任务调度。

use Illuminate\Support\Facades\Schedule;

// 每天凌晨 2 点执行
Schedule::command('orders:prune --days=90')->dailyAt('2:00');

// 每周一 9 点执行
Schedule::command('import:products storage/weekly.csv')->weeklyOn(1, '9:00');

命令的测试

可以使用 Laravel 的测试功能来验证 Artisan 命令的行为。

<?php

namespace Tests\Feature\Commands;

use App\Models\Order;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class PruneOldOrdersTest extends TestCase
{
    use RefreshDatabase;

    public function test_it_deletes_old_completed_orders(): void
    {
        // 创建 90 天前的已完成订单
        Order::factory()->create([
            'status'     => 'completed',
            'created_at' => now()->subDays(100),
        ]);

        // 最近的已完成订单（不应被删除）
        Order::factory()->create([
            'status'     => 'completed',
            'created_at' => now()->subDays(10),
        ]);

        $this->artisan('orders:prune', ['--days' => 90])
            ->expectsConfirmation('是否删除 90 天以上前的已完成订单？', 'yes')
            ->expectsOutput('已删除 1 条订单数据。')
            ->assertExitCode(0);

        $this->assertDatabaseCount('orders', 1);
    }

    public function test_it_cancels_when_user_declines(): void
    {
        Order::factory()->create(['status' => 'completed', 'created_at' => now()->subDays(100)]);

        $this->artisan('orders:prune', ['--days' => 90])
            ->expectsConfirmation('是否删除 90 天以上前的已完成订单？', 'no')
            ->expectsOutput('已取消。')
            ->assertExitCode(0);

        $this->assertDatabaseCount('orders', 1);
    }
}

artisan() 方法可用的断言方法示例：

方法	说明
`expectsOutput('...')`	验证输出中包含指定文本
`expectsQuestion('?', '回答')`	模拟 `ask()` 的输入
`expectsConfirmation('?', 'yes')`	模拟 `confirm()` 的响应
`expectsChoice('?', '选项')`	模拟 `choice()` 的选择
`assertExitCode(0)`	验证退出码（0 = 成功）
`assertFailed()`	验证退出码非 0

`dev` 命令

dev Artisan 命令可将本地开发所需的多个进程集中在一个终端窗口中一起启动。默认情况下，会并行运行 PHP 开发服务器、队列 Worker、通过 Pail 的日志监视以及 Vite 的资源编译。

php artisan dev

内部使用名为 concurrently 的 npm 包管理进程。各进程都会带上标签并区分颜色，从终端输出可以很容易地区分哪个进程。任意一个进程失败时，其他所有进程也会自动停止。默认执行的进程如下。

名称	命令
`server`	`php artisan serve --host=localhost`
`queue`	`php artisan queue:listen --tries=1 --timeout=0`
`logs`	`php artisan pail --timeout=0`
`vite`	`npm run dev`

vite 进程会自动检测正在使用的 Node 包管理器（npm、pnpm、Yarn、Bun）并使用相应的执行命令。

`dev` 进程的自定义

dev 命令执行的进程可以通过 DevCommands 类自定义。通常在应用程序的 AppServiceProvider 的 boot 方法内注册。register 方法接收命令字符串和可选的进程名。

use Illuminate\Foundation\DevCommands;

/**
 * 应用服务的初始启动处理
 */
public function boot(): void
{
    DevCommands::register('some-command --flag', 'my-process');
}

在注册 Artisan 命令时，可以使用 artisan 方法，它会自动在前面加上 php artisan。

DevCommands::artisan('horizon', 'horizon');

同样，node 方法会在前面加上检测到的包管理器的执行命令（例如 npm run），nodeExec 方法会加上包管理器的 exec 命令（例如 npx）。

DevCommands::node('storybook', 'storybook');

DevCommands::nodeExec('tailwindcss -i resources/css/app.css -o public/css/app.css --watch', 'tailwind');

以与默认进程相同的名称注册进程时，会替换该默认进程。例如可以自定义使 server 进程使用其他端口。

DevCommands::artisan('serve --host=localhost --port=9000', 'server');

也可以自定义终端中进程标签的颜色。可用的颜色方法有 blue、purple、pink、orange、green、yellow。也可以向 color 方法传入自定义 hex 颜色。

DevCommands::register('my-command', 'my-process')->green();

DevCommands::register('my-command', 'my-process')->color('#ff6347');

如果希望只列出已注册的 dev 进程而不实际启动，可以使用 dev:list 命令。

php artisan dev:list

`dev` 进程的过滤

使用 only 方法可以在执行 dev 命令时仅启动指定的进程。同样也可以通过 except 方法排除特定进程。

// 只启动 server 和 vite 进程...
DevCommands::only('server', 'vite');

// 启动除队列 Worker 之外的所有进程...
DevCommands::except('queue');

在本地开发中同时使用 Horizon、Reverb 等时，通过 DevCommands::artisan() 注册后，仅需一条 php artisan dev 即可全部启动，非常方便。

常用命令一览

# 新建命令
php artisan make:command CommandName

# 可用命令列表
php artisan list

# 查看命令的使用方法
php artisan help command:name

# 启动 Tinker
php artisan tinker

​什么是 Artisan

​Tinker

​自定义命令的创建

​生成命令

​命令的基本结构

​参数和选项的定义

​获取参数和选项

​input() — 类型化访问器

​与用户的交互

​消息的输出

​向用户提问

​进度条

​实用场景

​数据导入命令

​定期维护命令

​与计划任务组合

​命令的测试

​dev 命令

​dev 进程的自定义

​dev 进程的过滤

​常用命令一览

什么是 Artisan

Tinker

自定义命令的创建

生成命令

命令的基本结构

参数和选项的定义

获取参数和选项

`input()` — 类型化访问器

与用户的交互

消息的输出

向用户提问

进度条

实用场景

数据导入命令

定期维护命令

与计划任务组合

命令的测试

`dev` 命令

`dev` 进程的自定义

`dev` 进程的过滤

常用命令一览