提供创建、加载和操作 Mix 任务的便利功能。

Mix 任务可以通过在以 Mix.Tasks. 开头的模块中使用 use Mix.Task 来定义，并且该模块定义了 run/1 函数。通常，任务模块位于 lib/mix/tasks/ 目录中，并且它们的文件名使用点号分隔符而不是下划线（例如 deps.clean.ex） - 尽管最终文件名并不重要。

例如

# lib/mix/tasks/echo.ex
defmodule Mix.Tasks.Echo do
  @moduledoc "Printed when the user requests `mix help echo`"
  @shortdoc "Echoes arguments"

  use Mix.Task

  @impl Mix.Task
  def run(args) do
    Mix.shell().info(Enum.join(args, " "))
  end
end

命令名称将对应于模块名称中 Mix.Tasks. 之后的部分。例如，模块名称为 Mix.Tasks.Deps.Clean 对应于任务名称 deps.clean。

run/1 函数将根据用户的终端接收传递的所有命令行参数的列表。

例如，如果上面 echo 任务中的 args 被检查，你可能会看到类似以下内容

$ mix echo 'A and B' C --test
["A and B", "C", "--test"]

use Mix.Task

当你使用 use Mix.Task 时，Mix.Task 模块将设置 @behaviour Mix.Task 并且为下面部分中记录的模块属性定义默认值。

模块属性

你可以通过设置模块属性来控制 Mix 任务的一些行为。本节记录了可用的属性。

@shortdoc

如果你希望在 mix help 上公开显示任务，请定义 @shortdoc 属性。如果你不希望你的任务通过 mix help 列出，请省略此属性。

@moduledoc

@moduledoc 属性可以覆盖 @shortdoc。如果使用 @moduledoc false 隐藏整个模块的文档，则该任务不会出现在 mix help 中。

@requirements

如果一个任务有需求，可以使用 @requirements 属性列出它们。需求是该任务需要运行的其他 Mix 任务。例如

@requirements ["app.config"]

一个任务通常依赖于以下任务之一

• "loadpaths" - 这确保依赖项可用并被编译。如果你将任务作为库的一部分发布供他人使用，并且你的任务不需要以任何方式与用户代码交互，这是推荐的依赖项

• "app.config" - 此外，还会编译和加载当前项目的运行时配置。如果你正在创建一个将在你的应用程序内或作为库的一部分使用的任务，并且该任务必须调用或与用户代码交互，这是推荐的最小依赖项

• "app.start" - 此外，还会启动当前项目及其依赖项的监督树

@recursive

如果你希望任务在伞形项目中的每个伞形子项目上运行，请设置 @recursive true。

@preferred_cli_env

设置此任务的首选 Mix 环境。例如，如果你的任务旨在用于测试，你可以设置

@preferred_cli_env :test

文档

用户可以通过运行 mix help my_task 来阅读公共 Mix 任务的文档。将显示的文档是任务模块的 @moduledoc。