Ace 命令行

本指南向你介绍 Ace 命令行。你将了解以下主题：

运行 Ace 命令
查看帮助文档
创建命令别名
以编程方式运行命令

概述

Ace 是 AdonisJS 的命令行框架，为你的应用中的所有控制台命令提供支持。无论是运行数据库迁移、创建控制器，还是构建自定义的 CLI 工具，Ace 都为所有命令行交互提供了基础。

该框架负责命令解析、参数校验、交互式提示和终端输出格式化，让你能够专注于构建命令逻辑，而无需处理 CLI 样板代码。每个 AdonisJS 应用默认都包含 Ace，可通过项目根目录中的 ace.js 入口文件访问。

了解如何有效使用 Ace 对于 AdonisJS 开发至关重要，因为你在开发和部署期间会不断地与它打交道。

运行 Ace 命令

你可以使用项目根目录中的 ace.js 文件执行 Ace 命令。该文件是所有命令行操作的入口点。

Warning

不要直接修改 ace.js 文件。如果你需要添加在 Ace 启动前运行的自定义代码，请将其放入 bin/console.ts 文件。

node ace
node ace make:controller
node ace migration:run

查看可用命令

要查看应用中所有可用命令的列表，请在不带任何参数的情况下运行 ace 入口文件，或显式使用 list 命令。

node ace

# 与上面相同
node ace list

两条命令都会显示相同的帮助界面，将已注册的所有命令按类别组织展示。

Note

帮助输出遵循 docopt 标准，这是一个命令行界面规范，可确保不同工具之间文档格式的一致性。

获取特定命令的帮助

每个 Ace 命令都包含内置的帮助文档。要查看某个特定命令的详细信息，包括其参数、标志和使用示例，请在任意命令后附加 --help 标志。

node ace make:controller --help

帮助界面会显示命令的描述、必需和可选参数、带说明的可用标志，以及使用示例。

控制颜色输出

Ace 会自动检测你的终端环境，并在终端不支持 ANSI 颜色时禁用彩色输出。不过，你可以使用 --ansi 标志手动控制颜色输出。

# 禁用颜色
node ace list --no-ansi

# 强制启用颜色
node ace list --ansi

在将命令输出重定向到文件，或在支持彩色终端输出的 CI/CD 环境中运行时，禁用颜色会很有用。

创建命令别名

命令别名为带有特定标志组合的常用命令提供了快捷方式。当你发现自己反复输入带有相同标志的同一命令时，这会特别有用。

你可以在 adonisrc.ts 文件中使用 commandsAliases 对象定义别名。每个别名将一个短名称映射到一个带标志的完整命令。

adonisrc.ts

export default defineConfig({
  commandsAliases: {
    /**
     * 创建一个单一的资源型控制器
     */
    resource: 'make:controller --resource --singular'
  }
})

定义后，你可以使用别名，而无需键入完整命令。你提供的任何额外参数都会被附加到展开后的命令之后。

# 使用别名
node ace resource users

# 展开为
node ace make:controller --resource --singular users

别名展开的工作原理

当你运行命令时，Ace 会遵循以下展开过程：

Ace 检查命令名称是否与 commandsAliases 对象中的任何别名匹配
如果找到匹配项，Ace 从别名值中提取第一个单词（空格之前的部分），并查找对应的命令
如果存在该名称的命令，Ace 会将别名值中的其余片段全部附加，以构成完整命令
最后，Ace 附加你运行别名时提供的任何参数或标志

例如，如果你运行：

node ace resource admin --help

Ace 会将其展开为：

node ace make:controller --resource --singular admin --help

展开过程会保留参数顺序，并允许你添加别名中定义的标志之外的额外标志。

以编程方式运行命令

你可以使用 ace 服务在应用代码内部执行 Ace 命令。这对于构建需要以编程方式触发命令的工作流很有用，例如在应用安装期间运行迁移，或根据用户操作生成文件。

ace 服务在你的应用启动后可用，确保命令执行前所有必要的服务和提供者都已加载。

import ace from '@adonisjs/core/services/ace'

/**
 * 执行命令并获取其结果
 */
const command = await ace.exec('make:controller', [
  'users',
  '--resource',
])

/**
 * 命令对象包含执行详情
 */
console.log(command.exitCode) // 0 表示成功，1 表示失败
console.log(command.result)   // 命令的返回值
console.log(command.error)    // 命令失败时返回的错误对象

在执行命令之前，你应该验证命令是否存在，以避免运行时错误。使用 ace.hasCommand 方法来检查命令的可用性。

import ace from '@adonisjs/core/services/ace'

/**
 * 启动 Ace 以加载所有已注册命令
 * （如果尚未加载）
 */
await ace.boot()

if (ace.hasCommand('make:controller')) {
  await ace.exec('make:controller', [
    'users',
    '--resource',
  ])
} else {
  console.log('Controller command not available')
}

ace.boot() 方法会在命令尚未加载时加载所有命令。这确保 hasCommand 检查能通过对照完整的命令注册表正确工作。

创建命令了解如何在 AdonisJS 中创建自定义的 Ace 命令