命令参考

在本指南中，我们将介绍框架核心和官方包随附的所有命令的用法。你也可以使用 node ace list 命令或 node ace <command-name> --help 命令查看命令帮助。

node ace list

帮助屏幕的输出是按照 docopt 标准格式化的。

serve

serve 使用 @adonisjs/assembler 包在开发环境中启动 AdonisJS 应用。你可以选择性地监听文件更改，并在每次文件更改时重启 HTTP 服务器。

node ace serve --hmr

serve 命令以子进程的方式启动开发服务器（通过 bin/server.ts 文件）。如果你想向子进程传递 node 参数，可以在命令名称之前定义它们。

node ace --no-warnings --inspect serve --hmr

以下是你可以传递给 serve 命令的可用选项列表。或者，使用 --help 标志查看命令的帮助。

--hmr

以 HMR 模式监听文件系统并重新加载服务器。

--watch

监听文件系统，并在每次文件更改时始终重启进程。

--poll

使用轮询来检测文件系统的更改。当你使用 Docker 容器进行开发时，可能想要使用轮询。

--clear | --no-clear

在每次文件更改后、显示新日志之前清空终端。使用 --no-clear 标志保留旧日志。

--assets | --no-assets

在 AdonisJS HTTP 服务器旁边启动资源打包开发服务器。使用 --no-assets 标志关闭资源打包开发服务器。

--assets-args

向资源管理器子进程传递命令行参数。例如，如果你使用 vite，可以如下定义其选项。

node ace serve --hmr --assets-args="--cors --open"

build

build 命令使用 @adonisjs/assembler 包来创建 AdonisJS 应用的生产构建。生成构建会执行以下步骤。

相关阅读：TypeScript 构建流程。

node ace build

以下是你可以传递给 build 命令的可用选项列表。或者，使用 --help 标志查看命令的帮助。

--ignore-ts-errors

当你的项目存在 TypeScript 错误时，build 命令会终止构建过程。不过，你可以使用 --ignore-ts-errors 标志忽略这些错误并完成构建。

--package-manager

build 命令会复制你的应用正在使用的包管理器的 package.json 文件以及对应的锁定文件。

我们使用 @antfu/install-pkg 包检测包管理器。不过，你可以通过显式提供包管理器名称来关闭检测。

--assets | --no-assets

将前端资源与后端应用一起打包。使用 --no-assets 标志关闭资源打包开发服务器。

--assets-args

向资源管理器子进程传递命令行参数。例如，如果你使用 vite，可以如下定义其选项。

node ace build --assets-args="--sourcemap --debug"

add

add 命令将 npm install <package-name> 和 node ace configure 命令组合在一起。因此，你无需运行两条独立的命令，而是可以使用 add 命令一次性安装并配置该包。

add 命令会自动检测你的应用所使用的包管理器，并使用它来安装该包。不过，你始终可以使用 --package-manager CLI 标志选择特定的包管理器。

# 安装并配置 @adonisjs/lucid 包
node ace add @adonisjs/lucid

# 以开发依赖方式安装该包并配置它
node ace add my-dev-package --dev

如果该包可以使用标志进行配置，你可以直接将它们传递给 add 命令。每个未知的标志都会被向下传递给 configure 命令。

node ace add @adonisjs/lucid --db=sqlite

--verbose: 启用 verbose 模式以显示包的安装和配置日志。
--force: 向下传递给 configure 命令。在配置包时强制覆盖文件。详见 configure 命令。
--package-manager: 定义用于安装该包的包管理器。值必须是 npm、pnpm、bun 或 yarn。
--dev: 以开发依赖方式安装该包。

configure

在安装包之后对其进行配置。该命令接受包名称作为第一个参数。

node ace configure @adonisjs/lucid

--verbose

启用 verbose 模式以显示包的安装日志。

--force

AdonisJS 的 stubs 系统不会覆盖现有文件。例如，如果你配置了 @adonisjs/lucid 包，而你的应用已经有一个 config/database.ts 文件，那么 configure 过程不会覆盖现有的配置文件。

不过，你可以使用 --force 标志强制覆盖文件。

eject

将给定包中的 stubs 导出到你的应用 stubs 目录。在以下示例中，我们将 make/controller stubs 复制到我们的应用中以进行修改。

generate:key

生成一个加密安全的随机密钥，并作为 APP_KEY 环境变量写入 .env 文件。

make:controller

创建一个新的 HTTP 控制器类。控制器创建在 app/controllers 目录中，并遵循以下命名约定。

形式：plural（复数）
后缀：controller
类名示例：UsersController
文件名示例：users_controller.ts

node ace make:controller users

你也可以像下面的示例一样生成带有自定义操作名称的控制器。

# 生成带有 "index"、"show" 和 "store" 方法的控制器
node ace make:controller users index show store

--singular: 强制控制器名称为单数形式。
--resource: 生成一个包含对资源执行 CRUD 操作的方法的控制器。
--api: --api 标志与 --resource 标志类似。不过，它不会定义 create 和 edit 方法，因为它们用于显示表单。

make:middleware

创建一个新的 HTTP 请求中间件。中间件存储在 app/middleware 目录中，并遵循以下命名约定。

形式：singular（单数）
后缀：middleware
类名示例：BodyParserMiddleware
文件名示例：body_parser_middleware.ts

node ace make:middleware bodyparser

--stack

通过显式定义栈来跳过中间件栈选择提示。值必须是 server、named 或 router。

node ace make:middleware bodyparser --stack=router

make:event

创建一个新的事件类。事件存储在 app/events 目录中，并遵循以下命名约定。

形式：NA
后缀：NA
类名示例：OrderShipped
文件名示例：order_shipped.ts
建议：你应当围绕某个操作的生命周期来为事件命名。例如：MailSending、MailSent、RequestCompleted 等等。

node ace make:event orderShipped

make:validator

创建一个新的 VineJS 校验器文件。校验器存储在 app/validators 目录中，每个文件可以导出多个校验器。

形式：singular（单数）
后缀：NA
文件名示例：user.ts
建议：你应当围绕应用的资源来创建校验器文件。

# 用于管理用户的校验器
node ace make:validator user

# 用于管理文章的校验器
node ace make:validator post

--resource

创建一个包含用于 create 和 update 操作的预定义校验器的校验器文件。

node ace make:validator post --resource

make:listener

创建一个新的事件监听器类。监听器类存储在 app/listeners 目录中，并遵循以下命名约定。

形式：NA
后缀：NA
类名示例：SendShipmentNotification
文件名示例：send_shipment_notification.ts
建议：事件监听器应当根据它们所执行的操作来命名。例如，发送发货通知邮件的监听器应命名为 SendShipmentNotification。

node ace make:listener sendShipmentNotification

--event

在创建事件监听器的同时生成一个事件类。

node ace make:listener sendShipmentNotification --event=shipment_received

make:service

创建一个新的服务类。服务类存储在 app/services 目录中，并遵循以下命名约定。

服务没有预定义的含义，你可以用它来抽取应用中的业务逻辑。例如，如果你的应用会生成大量 PDF，你可以创建一个名为 PdfGeneratorService 的服务，并在多个地方复用它。

形式：singular（单数）
后缀：service
类名示例：InvoiceService
文件名示例：invoice_service.ts

node ace make:service invoice

make:exception

创建一个新的自定义异常类。异常存储在 app/exceptions 目录中。

形式：NA
后缀：exception
类名示例：CommandValidationException
文件名示例：command_validation_exception.ts

node ace make:exception commandValidation

make:command

创建一个新的 Ace 命令。默认情况下，命令存储在应用根目录的 commands 目录中。

当你尝试执行任何 Ace 命令时，AdonisJS 会自动导入此目录中的命令。你可以在文件名前加上 _ 前缀，以在此目录中存储其他非 Ace 命令的文件。

形式：NA
后缀：NA
类名示例：ListRoutes
文件名示例：list_routes.ts
建议：命令应当围绕它们所执行的操作来命名。例如：ListRoutes、MakeController 和 Build。

node ace make:command listRoutes

make:view

创建一个新的 Edge.js 模板文件。模板创建在 resources/views 目录中。

形式：NA
后缀：NA
文件名示例：posts/view.edge
建议：你应当将某个资源的模板归组到一个子目录中。例如：posts/list.edge、posts/create.edge 等等。

node ace make:view posts/create
node ace make:view posts/list

make:provider

创建一个服务提供者文件。提供者存储在应用根目录的 providers 目录中，并遵循以下命名约定。

形式：singular（单数）
后缀：provider
类名示例：AppProvider
文件名示例：app_provider.ts

node ace make:provider app

--environments

定义应该导入该提供者的环境。了解更多关于应用环境的信息

node ace make:provider app -e=web -e=console

make:preload

创建一个新的预加载文件。预加载文件存储在 start 目录中。

node ace make:preload view

--environments

定义应该导入该预加载文件的环境。了解更多关于应用环境的信息

node ace make:preload view app -e=web -e=console

make:test

在 tests/<suite> 目录中创建一个新的测试文件。

形式：NA
后缀：.spec
文件名示例：posts/list.spec.ts、posts/update.spec.ts

node ace make:test --suite=unit

--suite: 定义你要为其创建测试文件的测试套件（suite）。否则，命令将显示一个用于选择套件的提示。

make:mail

在 app/mails 目录中创建一个新的邮件类。邮件类以 Notification 关键字作为后缀。不过，你可以使用 --intent CLI 标志定义自定义后缀。

形式：NA
后缀：Intent
类名示例：ShipmentNotification
文件名示例：shipment_notification.ts

node ace make:mail shipment
# ./app/mails/shipment_notification.ts

--intent

为邮件定义自定义意图。

node ace make:mail shipment --intent=confirmation
# ./app/mails/shipment_confirmation.ts

node ace make:mail storage --intent=warning
# ./app/mails/storage_warning.ts

make:policy

创建一个新的 Bouncer 策略类。策略存储在 app/policies 文件夹中，并遵循以下命名约定。

形式：singular（单数）
后缀：policy
类名示例：PostPolicy
文件名示例：post_policy.ts

node ace make:policy post

inspect:rcfile

在合并默认值之后查看 adonisrc.ts 文件的内容。你可以使用此命令来检查可用的配置选项，并根据你的应用需求覆盖它们。

list:routes

查看你的应用注册的所有路由列表。该命令会在 console 环境中启动你的 AdonisJS 应用。

node ace list:routes

此外，如果你正在使用我们的官方 VSCode 扩展，你也可以从 VSCode 活动栏中查看路由列表。

--json: 以 JSON 字符串形式查看路由。输出将是一个对象数组。
--table: 在 CLI 表格中查看路由。默认情况下，我们以紧凑、美观的列表形式显示路由。
--middleware: 筛选路由列表，只包含使用所指定中间件的路由。你可以使用 * 关键字来包含使用一个或多个中间件的路由。
--ignore-middleware: 筛选路由列表，只包含未使用所指定中间件的路由。你可以使用 * 关键字来包含不使用任何中间件的路由。

env:add

env:add 命令允许你向 .env、.env.example 文件添加一个新的环境变量，并且还会在 start/env.ts 文件中定义校验规则。

你可以直接运行该命令，它会提示你输入变量名、值和校验规则。或者你也可以将它们作为参数传递。

# 将提示你输入变量名、值和校验规则
node ace env:add

# 定义变量名、值和校验规则
node ace env:add MY_VARIABLE value --type=string

--type

定义环境变量的类型。值必须是以下之一：string、boolean、number、enum。

--enum-values

当类型为 enum 时，定义环境变量的允许值。

node ace env:add MY_VARIABLE foo --type=enum --enum-values=foo --enum-values=bar

Ace 命令

终端界面

参考资料

Edge 辅助函数与标签