任务

Zed 支持使用其集成终端来生成（并重新运行）命令以输出结果。这些命令可以读取 Zed 状态的有限子集（例如当前正在编辑的文件路径或选定的文本）。

[
  {
    "label": "Example task",
    "command": "for i in {1..5}; do echo \"Hello $i/5\"; sleep 1; done",
    //"args": [],
    // Env overrides for the command, will be appended to the terminal's environment from the settings.
    "env": { "foo": "bar" },
    // Current working directory to spawn the command into, defaults to current project root.
    //"cwd": "/path/to/working/directory",
    // Whether to use a new terminal tab or reuse the existing one to spawn the process, defaults to `false`.
    "use_new_terminal": false,
    // Whether to allow multiple instances of the same task to be run, or rather wait for the existing ones to finish, defaults to `false`.
    "allow_concurrent_runs": false,
    // What to do with the terminal pane and tab, after the command was started:
    // * `always` — always show the task's pane, and focus the corresponding tab in it (default)
    // * `no_focus` — always show the task's pane, add the task's tab in it, but don't focus it
    // * `never` — do not alter focus, but still add/reuse the task's tab in its pane
    "reveal": "always",
    // What to do with the terminal pane and tab, after the command has finished:
    // * `never` — Do nothing when the command finishes (default)
    // * `always` — always hide the terminal tab, hide the pane also if it was the last tab in it
    // * `on_success` — hide the terminal tab on task success only, otherwise behaves similar to `always`
    "hide": "never",
    // Which shell to use when running a task inside the terminal.
    // May take 3 values:
    // 1. (default) Use the system's default terminal configuration in /etc/passwd
    //      "shell": "system"
    // 2. A program:
    //      "shell": {
    //        "program": "sh"
    //      }
    // 3. A program with arguments:
    //     "shell": {
    //         "with_arguments": {
    //           "program": "/bin/bash",
    //           "args": ["--login"]
    //         }
    //     }
    "shell": "system",
    // Whether to show the task line in the output of the spawned task, defaults to `true`.
    "show_summary": true,
    // Whether to show the command line in the output of the spawned task, defaults to `true`.
    "show_command": true
    // Represents the tags for inline runnable indicators, or spawning multiple tasks at once.
    // "tags": []
  }
]

有两个操作驱动任务的使用流程：task: spawn 和 task: rerun。task: spawn 会打开一个模态框，其中包含当前文件中所有可用的任务。task: rerun 会重新运行最近生成的任务。你也可以从任务模态框中重新运行任务。

默认情况下，重新运行任务会重用同一个终端（因为默认设置为 "use_new_terminal": false），但在开始之前会等待上一个任务完成（因为默认设置为 "allow_concurrent_runs": false）。

保持 "use_new_terminal": false 并设置 "allow_concurrent_runs": true 以允许在重新运行时取消之前的任务。

任务模板

任务可以定义在

• 全局 tasks.json 文件中；此类任务在您处理的所有 Zed 项目中都可用。此文件通常位于 ~/.config/zed/tasks.json。您可以使用 zed: open tasks 操作编辑它们。
• 特定于工作树（本地）的 .zed/tasks.json 文件中；此类任务仅在处理包含该工作树的项目时可用。您可以使用 zed: open project tasks 操作编辑特定于工作树的任务。
• 通过一次性任务即时定义。这些任务是项目特定的，并且不会在会话之间持久存在。
• 通过语言扩展。

变量

Zed 任务就像您的 shell 一样；这也意味着您可以通过类 sh 的 $VAR_NAME 语法引用环境变量。为了您的方便，还设置了一些额外的环境变量。这些变量允许您从当前编辑器中提取信息并在任务中使用。以下变量可用

• ZED_COLUMN：当前行号
• ZED_ROW：当前列号
• ZED_FILE：当前打开文件的绝对路径（例如 /Users/my-user/path/to/project/src/main.rs）
• ZED_FILENAME：当前打开文件的文件名（例如 main.rs）
• ZED_DIRNAME：当前打开文件的绝对路径，不带文件名（例如 /Users/my-user/path/to/project/src）
• ZED_RELATIVE_FILE：当前打开文件的路径，相对于 ZED_WORKTREE_ROOT（例如 src/main.rs）
• ZED_RELATIVE_DIR：当前打开文件目录的路径，相对于 ZED_WORKTREE_ROOT（例如 src）
• ZED_STEM：当前打开文件的名称（不带扩展名）（例如 main）
• ZED_SYMBOL：当前选定的符号；应与符号面包屑中显示的最后一个符号匹配（例如 mod tests > fn test_task_contexts）
• ZED_SELECTED_TEXT：当前选定的文本
• ZED_WORKTREE_ROOT：当前工作树根目录的绝对路径。（例如 /Users/my-user/path/to/project）
• ZED_CUSTOM_RUST_PACKAGE：（Rust 专用）$ZED_FILE 源文件的父包名称。

要在任务中使用变量，请在其前面加上美元符号 ($)

{
  "label": "echo current file's path",
  "command": "echo $ZED_FILE"
}

您还可以使用详细语法，如果给定变量不可用，则可以指定默认值：${ZED_FILE:default_value}

这些环境变量也可以在任务的 cwd、args 和 label 字段中使用。

变量引用

当处理包含空格或其他特殊字符的路径时，请确保变量已正确转义。

例如，不要使用以下方法（如果路径包含空格，则会失败）

{
  "label": "stat current file",
  "command": "stat $ZED_FILE"
}

提供以下内容

{
  "label": "stat current file",
  "command": "stat",
  "args": ["$ZED_FILE"]
}

或者明确包含转义引号，如下所示

{
  "label": "stat current file",
  "command": "stat \"$ZED_FILE\""
}

基于变量的任务过滤

在确定任务列表时，如果变量不存在，则会过滤掉包含该变量的任务定义。例如，以下任务仅在有文本选择时才会出现在生成模态框中

{
  "label": "selected text",
  "command": "echo \"$ZED_SELECTED_TEXT\""
}

为此类变量设置默认值，以使此类任务始终显示。

{
  "label": "selected text with default",
  "command": "echo \"${ZED_SELECTED_TEXT:no text selected}\""
}

一次性任务

通过 task: spawn 打开的相同任务模态框支持任意类 bash 命令执行：在模态文本字段中输入命令，然后使用 opt-enter 生成它。

任务模态框会在会话期间保留这些临时命令，如果它们是最后生成的任务，task: rerun 也会重新运行此类任务。

您还可以调整模态框中当前选定的任务（tab 是默认的键绑定）。这样做会将其命令放入提示符中，然后可以将其编辑并生成为一次性任务。

临时任务

您可以在通过模态框生成任务时使用 cmd 修饰符；以这种方式生成的任务不会增加其使用计数（因此，它们不会通过 task: rerun 重新生成，并且在任务模态框中的排名也不会很高）。临时任务的预期用途是在持续使用 task: rerun 的流程中保持一致。

更多任务重新运行控制

默认情况下，任务会将其变量捕获到一个上下文中一次，并且此“已解析任务”始终会重新运行。

这可以通过任务的 "reevaluate_context" 参数控制：将其设置为 true 将强制任务在每次运行前重新评估。

{
  "context": "Workspace",
  "bindings": {
    "alt-t": ["task::Rerun", { "reevaluate_context": true }]
  }
}

任务的自定义键绑定

您可以通过 task::Spawn 的附加参数为您的任务定义自己的键绑定。如果您想将上述 echo current file's path 任务绑定到 alt-g，您需要在 keymap.json 文件中添加以下代码片段

{
  "context": "Workspace",
  "bindings": {
    "alt-g": ["task::Spawn", { "task_name": "echo current file's path" }]
  }
}

请注意，这些任务还可以指定“目标”来控制生成的任务应该显示在哪里。这对于启动您想要在中心区域使用的终端应用程序可能很有用

// In tasks.json
{
  "label": "start lazygit",
  "command": "lazygit -p $ZED_WORKTREE_ROOT"
}

// In keymap.json
{
  "context": "Workspace",
  "bindings": {
    "alt-g": [
      "task::Spawn",
      { "task_name": "start lazygit", "reveal_target": "center" }
    ]
  }
}

将可运行标签绑定到任务模板

Zed 支持通过工作区本地和全局 tasks.json 文件覆盖内联可运行指示器的默认操作，优先级如下

1. 工作区 tasks.json
2. 全局 tasks.json
3. 语言提供的标签绑定（默认）。

要标记任务，请将可运行标签名称添加到任务模板上的 tags 字段

{
  "label": "echo current file's path",
  "command": "echo $ZED_FILE",
  "tags": ["rust-test"]
}

通过这样做，您可以更改在可运行指示器中显示的任务。

运行绑定到可运行项的任务的键绑定

当您有一个绑定到可运行项的任务定义时，您可以使用代码操作快速运行它，您可以通过 editor: Toggle Code Actions 命令或 cmd-./ctrl-. 快捷方式触发。您的任务将是下拉列表中的第一个。如果该行没有其他代码操作，任务将立即运行。