配置

快速入门

虽然 Nushell 提供了许多用于管理其启动和配置的选项，但新用户只需几个简单的步骤即可开始：

1. 告诉 Nushell 使用哪个编辑器：

   $env.config.buffer_editor = "<path_to_your_preferred_editor>"

   例如：

   $env.config.buffer_editor = ["code", "-w"]
   # 或
   $env.config.buffer_editor = "nano"
   # 或
   $env.config.buffer_editor = "hx"
   # 或
   $env.config.buffer_editor = "vi"
   # 带参数
   $env.config.buffer_editor = ["emacsclient", "-s", "light", "-t"]
   # 等等

2. 使用以下命令编辑 config.nu：

   config nu

   这将在上面定义的编辑器中打开当前的 config.nu。

3. 将每次 Nushell 启动时应运行的命令添加到此文件中。一个很好的初始示例可能是上面的 buffer_editor 设置。

   你可以使用以下命令找到可用设置的详细列表：

    config nu --doc | nu-highlight | less -R

4. 保存、退出编辑器，然后启动一个新的 Nushell 会话以加载这些设置。

就是这样！需要时，下面有更多详细信息...

config nu --doc | nu-highlight | less -R

配置概述

Nushell 使用多个可选的配置文件。这些文件按以下顺序加载：

1. 加载的第一个文件是 env.nu，历史上用于覆盖环境变量。但是，当前的“最佳实践”建议是使用 config.nu 和下面的自动加载目录来设置所有环境变量（和其他配置）。

2. config.nu 通常用于覆盖默认的 Nushell 设置、定义（或导入）自定义命令，或运行任何其他启动任务。

3. 加载 $nu.vendor-autoload-dirs 中的 *.nu 文件。这些目录旨在用于供应商和包管理器的启动文件。

4. 加载 $nu.user-autoload-dirs 中的 *.nu 文件。这些文件可用于任何启动任务，是模块化配置的好方法。

5. login.nu 运行仅在 Nushell 作为登录 shell 运行时才应发生的命令或处理配置。

默认情况下，env.nu、config.nu 和 login.nu 从 $nu.default-config-dir 目录中读取。例如：

$nu.default-config-dir
# macOS
# => /Users/me/Library/Application Support/nushell
# Linux
# => /home/me/.config/nushell
# Windows
# => C:\Users\me\AppData\Roaming\nushell

Nushell 首次启动时，将创建配置目录以及一个空的（除了注释）env.nu 和 config.nu。

$env.config.buffer_editor = 'code'

config.nu 中的常见配置任务：

config.nu 通常用于：

• 为 Nushell 和其他应用程序设置环境变量
• 在 $env.config 中设置 Nushell 设置
• 加载模块或源文件，以便其命令随时可用
• 在启动时运行任何其他应用程序或命令

设置环境变量

路径配置

与大多数 shell 一样，Nushell 搜索名为 PATH（或其变体）的环境变量。

当 Nushell 启动时，它通常继承 PATH 作为一个字符串。但是，Nushell 会自动将其转换为 Nushell 列表以便于访问。这意味着你可以使用例如以下方式追加到路径：

$env.path ++= ["~/.local/bin"]

标准库还包括一个辅助命令。默认的 path add 行为是前置一个目录，使其比路径的其余部分具有更高的优先级。例如，可以将以下内容添加到你的启动配置中：

use std/util "path add"
path add "~/.local/bin"
path add ($nu.home-dir | path join ".cargo" "bin")

提示符配置

Nushell 提供了许多提示符配置选项。默认情况下，Nushell 包括：

• 一个包含当前目录的提示符，如果它在主目录下（或其子目录），则使用 ~ 缩写。
• 一个紧接在提示符右侧的提示指示符。在正常编辑模式下，默认为 > ，在 Vi 插入模式下为 : 。请注意字符后的额外空格，以提供命令与提示符之间的分隔。
• 一个带有日期和时间的右提示符
• 一个在当前命令行跨越多行时显示的指示符 - 默认为 :::

控制这些提示符组件的环境变量是：

• $env.PROMPT_COMMAND: 提示符本身
• $env.PROMPT_COMMAND_RIGHT: 可以出现在终端右侧的提示符
• $env.PROMPT_INDICATOR: Emacs 模式指示符
• $env.PROMPT_INDICATOR_VI_NORMAL: Vi-normal 模式指示符
• $env.PROMPT_INDICATOR_VI_INSERT: Vi-insert 模式指示符
• $env.PROMPT_MULTILINE_INDICATOR: 多行指示符

这些变量中的每一个都接受以下任一值：

• 一个字符串，在这种情况下，组件将静态显示为该字符串。
• 一个闭包（无参数），在这种情况下，组件将根据闭包的代码动态显示。
• null，在这种情况下，组件将恢复为其内部默认值。

$env.PROMPT_COMMAND_RIGHT = ""
# 或
$env.PROMPT_COMMAND_RIGHT = {||}

瞬态提示符

Nushell 还支持瞬态提示符，它允许在执行命令行后显示不同的提示符。这在几种情况下很有用：

• 使用多行提示符时，瞬态提示符可以是更精简的版本。
• 删除瞬态多行指示符和右提示符可以简化从终端的复制。

与上面的普通提示符命令一样，每个瞬态提示符都可以接受一个（静态）字符串、一个（动态）闭包或一个 null 以使用 Nushell 内部默认值。

控制瞬态提示符组件的环境变量是：

• $env.TRANSIENT_PROMPT_COMMAND: 执行命令行后的提示符本身
• $env.TRANSIENT_PROMPT_COMMAND_RIGHT: 可以出现在终端右侧的提示符
• $env.TRANSIENT_PROMPT_INDICATOR: Emacs 模式指示符
• $env.TRANSIENT_PROMPT_INDICATOR_VI_NORMAL: Vi-normal 模式指示符
• $env.TRANSIENT_PROMPT_INDICATOR_VI_INSERT: Vi-insert 模式指示符
• $env.TRANSIENT_PROMPT_MULTILINE_INDICATOR: 多行指示符

$env.TRANSIENT_PROMPT_COMMAND_RIGHT = null
$env.TRANSIENT_PROMPT_MULTILINE_INDICATOR = null

缓慢的提示符段

一个运行时间较长的提示符闭包（例如调用 git 的闭包）会拖慢每一次提示符的显示。 这时可以让闭包启动一个后台任务并立即返回。任务完成后， 它会调用 commandline set-prompt 来补上缺失的部分， 而不会干扰正在编辑的行。例如，要在右侧提示符中显示当前的 Git 分支：

$env.PROMPT_COMMAND_RIGHT = {
    job spawn {
        let branch = (git branch --show-current | complete | get stdout | str trim)
        commandline set-prompt --right $"(ansi yellow)($branch)(ansi reset)"
    }

    ""  # 在后台任务填充之前，右侧不显示任何内容
}

commandline set-prompt 默认设置左侧提示符。使用 --right、--indicator、--vi-insert、--vi-normal 或 --multiline 可以设置其他提示符组件。新文本会一直保留到下一次绘制提示符为止。

由提示符闭包，或由 pre_prompt / env_change 钩子 启动的任务，可能在提示符绘制之前就完成（例如 git 响应很快时）。此时它的 commandline set-prompt 仍会显示在那一次提示符上。当钩子或提示符闭包直接调用 commandline set-prompt 时也是如此：推送的文本会替换提示符变量为该段提供的内容。

ENV_CONVERSIONS

某些变量，例如包含多个路径的变量，通常在其他 shell 中存储为以冒号分隔的字符串。Nushell 可以自动将这些转换为更方便的 Nushell 列表。ENV_CONVERSIONS 变量指定了环境变量如何：

• 从字符串转换为值（from_string）。这在 $env.ENV_CONVERSIONS 被赋值时立即发生，针对那一刻存在的每个已列出的变量（例如从父进程继承来的那个）。
• 在运行外部命令时从值转换回字符串 (to_string)

ENV_CONVERSIONS 是一个记录，其中：

• 每个键是要转换的环境变量
• 每个值是另一个包含以下内容的记录：

  {
    from_string: <closure>
    to_string: <closure>
  }

要添加其他转换，请使用 merge 将其合并到 $env.ENV_CONVERSIONS 记录中。例如，要为 XDG_DATA_DIRS 变量添加转换：

$env.ENV_CONVERSIONS = $env.ENV_CONVERSIONS | merge {
    "XDG_DATA_DIRS": {
        from_string: {|s| $s | split row (char esep) | path expand --no-symlink }
        to_string: {|v| $v | path expand --no-symlink | str join (char esep) }
    }
}

LS_COLORS

与许多类似 ls 的实用程序一样，Nushell 的目录列表利用 LS_COLORS 环境变量来定义应用于某些文件类型和模式的样式/颜色。

$env.config 记录中的 Nushell 设置

在 $env.config 记录中更改设置

更改 Nushell 行为的主要机制是 $env.config 记录。虽然此记录作为环境变量访问，但与大多数其他变量不同，它：

• 不会从父进程继承。相反，它由 Nushell 本身用某些默认值填充。
• 不会导出到由 Nushell 启动的子进程。

要检查 $env.config 中的当前设置，只需键入变量名：

$env.config

$env.config | table -e | less -R
# 或者，如果安装了 bat：
$env.config | table -e | bat -p

可以使用以下命令在 Nushell 中查看每个设置的缩写文档：

config nu --doc | nu-highlight | bat
# 或
config nu --doc | nu-highlight | less -R

一些较新添加的设置包括：

• error_style："fancy"（默认值）、"plain"、"short" 用于简洁的单行错误消息，或 "nested" 将相关错误嵌套显示在主要错误之下。error_lines 设置错误位置周围显示的源代码行数（默认为 1）。
• auto_cd_implicit：当为 true 时，只输入子目录的名称（例如 src）就会进入该目录。默认情况下，自动切换目录需要 ./src 这样的路径。
• history.path：历史文件的自定义位置，或设为 null 来禁用历史记录。history.ignore_space_prefixed（默认为 true）可以让以空格开头的命令不进入历史记录。
• completions.cache_size：要记住多少个 Tab 补全前缀（默认为 100；0 表示禁用缓存）。completions.persistent_menus：当为 true 时，补全和历史菜单在你编辑命令行时保持打开。

为避免覆盖现有设置，最好只为所需的配置键分配更新的值，而不是整个 config 记录。换句话说：

$env.config = {
  show_banner: false
}

$env.config.show_banner = false

某些键本身也是记录。覆盖这些记录是可以的，但最佳实践是在这样做时设置所有值。例如：

# In config.nu
$env.config.history = {
  file_format: sqlite
  max_size: 1_000_000
  sync_on_enter: true
  isolation: true
}

删除欢迎消息

要删除每次 Nushell 启动时显示的欢迎消息：

1. 键入 config nu 来编辑你的配置文件。

2. 如果你收到有关未定义编辑器的错误：

   $env.config.buffer_editor = "<path to your preferred editor>"
   # 例如：
   $env.config.buffer_editor = "code"
   $env.config.buffer_editor = "vi"
   # 或带编辑器参数：
   $env.config.buffer_editor = ["emacsclient", "-s", "light", "-t"]

   然后重复步骤 1。

3. 将以下行添加到文件末尾：

   $env.config.show_banner = false

4. 保存并退出你的编辑器。

5. 重新启动 Nushell 以测试更改。

其他启动配置

更改默认目录

一些控制 Nushell 启动文件位置的变量必须在 Nushell 加载之前设置。这通常由父进程完成，例如：

• 运行 Nushell 的终端应用程序

• 操作系统或窗口管理器。当将 Nushell 作为登录 shell 运行时，这可能是唯一可用的机制。

  例如，在 Windows 上，你可以通过控制面板设置环境变量。选择开始菜单并搜索*“环境变量”*。

  在使用 PAM 的 Linux 系统上，可以使用 /etc/environment（以及其他系统特定的机制）。

• 父 shell。例如，在运行 nu 之前从 bash 导出值。

启动变量

影响 Nushell 文件位置的变量是：

• $env.XDG_CONFIG_HOME: 如果设置了此环境变量，它将用于更改 Nushell 搜索其配置文件（如 env.nu、config.nu、login.nu 和 <config>/autoload 目录）的目录。历史记录和插件文件默认也存储在此目录中。

  Nushell 启动后，此值存储在 $nu.default-config-dir 常量中。请参阅下面的使用常量。

  启动 nu 时也可以通过 --config-home <path> 标志选择配置目录，它优先于 XDG_CONFIG_HOME。与 XDG_CONFIG_HOME 不同，传给 --config-home 的路径就是 Nushell 配置目录本身（不会再附加 nushell 子目录），而相对路径是相对于当前目录解析的。

• $env.XDG_DATA_HOME: 如果设置了此环境变量，Nushell 会将 $nu.data-dir 常量设置为 ($env.XDG_DATA_HOME)/nushell。data-dir 用于多个启动任务：

  • ($nu.data-dir)/completions 被添加到 const 变量 $NU_LIB_DIRS 以及 $env.NU_LIB_DIRS（后者以相同的默认列表起始）。常量是配置搜索路径的首选方式；参见下文的 NU_LIB_DIRS 常量。
  • ($nu.data-dir)/vendor/autoload 被添加到 $nu.vendor-autoload-dirs 中，位于系统供应商目录（例如来自 XDG_DATA_DIRS 的那些）之后。此目录中的文件将在其他供应商自动加载目录之后读取，从而覆盖其任何设置。

  请注意，由 $nu.data-dir 表示的目录及其任何子目录默认情况下都不会创建。这些目录的创建和使用由用户决定。

• $env.XDG_DATA_DIRS （仅限 Unix 平台）：如果设置了此环境变量，它将用于填充 $nu.vendor-autoload-dirs 目录。遵循 XDG 约定（靠前的条目优先级更高），这些目录以相反顺序处理：XDG_DATA_DIRS 中的第一个目录最后读取，从而能够覆盖其他目录中的定义。

/users/username/dotfiles/nushell

/users/username/dotfiles

# 创建一个空的临时目录
let temp_home = (mktemp -d)
# 将配置路径设置为此目录
$env.XDG_CONFIG_HOME = $temp_home
# 将数据目录设置为此目录
$env.XDG_DATA_HOME = $temp_home
# 替换默认的 XDG_DATA_DIRS 供应商自动加载目录（仅限 Unix）
$env.XDG_DATA_DIRS = $temp_home
# 在此环境中运行 Nushell
nu

# 编辑配置
config nu
# 退出子 shell
exit
# 运行临时配置
nu

# 如果需要，删除临时配置目录
rm -r $temp_home

使用常量

一些重要的命令，如 source 和 use，有助于定义自定义命令（和其他定义），它们是解析时关键字。除其他外，这意味着所有参数必须在解析时已知。

换句话说， 解析时关键字不允许使用变量参数 。

但是，Nushell 创建了一些方便的常量，可用于帮助识别常见的文件位置。例如，你可以使用以下命令从默认配置目录中加载文件：

source ($nu.default-config-dir | path join "myfile.nu")

因为常量值在解析时已知，所以它可以与 source 和 use 等解析时关键字一起使用。

$nu 常量

要查看内置 Nushell 常量的列表，请使用 $nu（包括美元符号）检查记录常量。

NU_LIB_DIRS 常量

NU_LIB_DIRS 常量 列出了 source、use 和 overlay use 搜索文件的目录。默认情况下，它包含配置目录下的 scripts 目录和 $nu.data-dir 下的 completions 目录。$env.NU_LIB_DIRS 环境变量以相同的列表起始且仍受支持，但常量是配置搜索路径的首选方式，因为与 $env.NU_LIB_DIRS 不同，它可以在 config.nu 中定义和使用。例如：

# 定义模块和源搜索路径
const NU_LIB_DIRS = [
  '~/myscripts'
]
# 从 ~/myscripts 目录加载 myscript.nu
source myscript.nu

如果同时定义了变量 $env.NU_LIB_DIRS 和常量 NU_LIB_DIRS，则将搜索两组路径。常量 NU_LIB_DIRS 将首先被搜索并具有优先权。如果在这些目录中找到匹配名称的文件，搜索将停止。否则，它将继续进入 $env.NU_LIB_DIRS 搜索路径。

NU_PLUGIN_DIRS 常量

const NU_PLUGIN_DIRS 对插件搜索路径的作用方式相同。

以下 NU_PLUGIN_DIRS 配置将允许从以下位置加载插件：

• nu 可执行文件所在的目录。这通常是发布包中插件所在的位置。
• $nu.data-dir 中以正在运行的 Nushell 版本命名的目录（例如 0.116.0）。
• 包含你的 config.nu（$nu.config-path）的目录中的 plugins 目录。

const NU_PLUGIN_DIRS = [
  ($nu.current-exe | path dirname)
  ($nu.data-dir | path join 'plugins' | path join (version).version)
  ($nu.config-path | path dirname | path join 'plugins')
]

颜色、主题和语法高亮

你可以在相关章节中了解有关设置颜色和主题的更多信息。

将 Nu 配置为登录 Shell

登录 shell 通常负责设置某些将由子 shell 和其他进程继承的环境变量。将 Nushell 设置为用户的默认登录 shell 时，你需要确保 login.nu 处理此任务。

许多应用程序会假定 POSIX 或 PowerShell 登录 shell，并提供修改由 POSIX 登录 shell 加载的系统或用户 profile（或 PowerShell 系统上的 .ps1 文件）的说明。

正如你现在可能已经注意到的，Nushell 不是 POSIX shell，也不是 PowerShell，它无法处理为这些 shell 编写的配置文件。你需要改为在 login.nu 中设置这些值。

要查找可能需要通过 login.nu 设置的环境变量，请通过从你以前的登录 shell 中运行 nu 来检查从登录 shell 继承的环境。运行：

$env | reject config | transpose key val | each {|r| echo $"$env.($r.key) = '($r.val)'"} | str join (char nl)

查找第三方应用程序可能需要的任何值，并将这些值复制到你的 login.nu 中。其中许多值将不需要。例如，PS1 设置是 POSIX shell 中的当前提示符，在 Nushell 中将无用。

准备好后，将 Nushell 添加到你的 /etc/shells (Unix) 并 chsh，如安装章节中所述。

macOS: 保持 /usr/bin/open 为 open

某些工具（如 Emacs）依赖于 open 命令在 Mac 上打开文件。

由于 Nushell 有自己的 open 命令，其含义不同，它会遮蔽（覆盖）/usr/bin/open，因此这些工具在尝试使用该命令时会产生错误。

解决此问题的一种方法是为 Nushell 的 open 定义一个自定义命令，并在你的 config.nu 文件中为系统的 open 创建一个别名，如下所示：

alias nu-open = open
alias open = ^open

将此行放入你的 config.nu 中以使其永久生效。

^ 符号告诉 Nushell 将以下命令作为外部命令运行，而不是作为 Nushell 内置命令。运行这些命令后，nu-open 将是 Nushell 内部版本，而 open 别名将调用 Mac 的外部 open。你也可以使用 % 符号来访问内置命令，例如 %open，即使别名遮蔽了它。

有关更多信息，请参阅运行系统（外部）命令。

详细的配置启动过程

本节包含有关如何使用不同的配置（和标志）选项来更改 Nushell 启动行为的更详细描述。

启动阶段

以下阶段及其步骤可能在启动期间发生，具体取决于传递给 nu 的标志。有关每个标志如何影响该过程，请参阅紧随此表之后的标志行为：

标志行为

场景

• nu:

  • ✅ 使标准库可用
  • ✅ 如果存在于配置目录中，则读取用户的 plugin.msgpackz 文件
  • ✅ 在内部加载 default_env.nu 文件
  • ✅ 如果存在于配置目录中，则加载用户的 env.nu 文件
  • ✅ 在内部加载 default_config.nu 文件
  • ✅ 如果存在于配置目录中，则加载用户的 config.nu 文件
  • ❌ 不读取个人 login.nu 文件
  • ✅ 加载 vendor-autoload-dirs 中的文件
  • ✅ 加载 user-autoload-dirs 中的文件
  • ✅ 进入 REPL

• nu -c "ls":

  • ✅ 使标准库可用
  • ✅ 如果存在于配置目录中，则读取用户的 plugin.msgpackz 文件
  • ✅ 在内部加载 default_env.nu 文件
  • ❌ 不加载用户的 env.nu
  • ❌ 不读取内部 default_config.nu 文件
  • ❌ 不读取用户的 config.nu 文件
  • ❌ 不读取用户的 login.nu 文件
  • ✅ 运行 ls 命令并退出
  • ❌ 不进入 REPL
  • ❌ 不加载 vendor-autoload-dirs 中的文件
  • ❌ 不加载 user-autoload-dirs 中的文件

• nu -l -c "ls":

  • ✅ 使标准库可用
  • ✅ 如果存在于配置目录中，则读取用户的 plugin.msgpackz 文件
  • ✅ 在内部加载 default_env.nu 文件
  • ✅ 如果存在于配置目录中，则加载用户的 env.nu 文件
  • ✅ 在内部加载 default_config.nu 文件
  • ✅ 如果存在于配置目录中，则加载用户的 config.nu 文件
  • ✅ 如果存在于配置目录中，则加载用户的 login.nu 文件
  • ✅ 运行 ls 命令并退出
  • ❌ 不进入 REPL
  • ❌ 不加载 vendor-autoload-dirs 中的文件
  • ❌ 不加载 user-autoload-dirs 中的文件

• nu -l -c "ls" --config foo_config.nu

  • 与上面相同，但会读取名为 foo_config.nu 的备用配置文件，而非用户的 config.nu。像这样的相对路径是相对于当前目录解析的，而不是配置目录

• nu -n -l -c "ls":

  • ✅ 使标准库可用
  • ❌ 不读取用户的 plugin.msgpackz
  • ❌ 不读取内部 default_env.nu
  • ❌ 不加载用户的 env.nu
  • ❌ 不读取内部 default_config.nu 文件
  • ❌ 不读取用户的 config.nu 文件
  • ❌ 不读取用户的 login.nu 文件
  • ✅ 运行 ls 命令并退出
  • ❌ 不进入 REPL
  • ❌ 不加载 vendor-autoload-dirs 中的文件
  • ❌ 不加载 user-autoload-dirs 中的文件

• nu test.nu:

  • ✅ 使标准库可用
  • ✅ 如果存在于配置目录中，则读取用户的 plugin.msgpackz 文件
  • ✅ 在内部加载 default_env.nu 文件
  • ❌ 不加载用户的 env.nu
  • ❌ 不读取内部 default_config.nu 文件
  • ❌ 不读取用户的 config.nu 文件
  • ❌ 不读取用户的 login.nu 文件
  • ✅ 作为脚本运行 test.nu 文件
  • ❌ 不进入 REPL
  • ❌ 不加载 vendor-autoload-dirs 中的文件
  • ❌ 不加载 user-autoload-dirs 中的文件

• nu --config foo_config.nu test.nu

  • ✅ 使标准库可用
  • ✅ 如果存在于配置目录中，则读取用户的 plugin.msgpackz 文件
  • ✅ 在内部加载 default_env.nu 文件
  • ❌ 不加载用户的 env.nu（未指定 --env-config）
  • ✅ 在内部加载 default_config.nu 文件。请注意，default_config.nu 总是在用户配置之前处理
  • ✅ 加载当前目录中的 foo_config.nu，而不是用户的 config.nu
  • ❌ 不读取用户的 login.nu 文件
  • ✅ 作为脚本运行 test.nu 文件
  • ❌ 不进入 REPL
  • ❌ 不加载 vendor-autoload-dirs 中的文件
  • ❌ 不加载 user-autoload-dirs 中的文件

• nu -n --no-std-lib (最快的 REPL 启动):

  • ❌ 不使标准库可用
  • ❌ 不读取用户的 plugin.msgpackz
  • ❌ 不读取内部 default_env.nu
  • ❌ 不加载用户的 env.nu
  • ❌ 不读取内部 default_config.nu 文件
  • ❌ 不读取用户的 config.nu 文件
  • ❌ 不读取用户的 login.nu 文件
  • ❌ 不加载 vendor-autoload-dirs 中的文件
  • ❌ 不加载 user-autoload-dirs 中的文件
  • ✅ 进入 REPL

• nu -n --no-std-lib -c "ls" (最快的命令字符串调用):

  • ❌ 不使标准库可用
  • ❌ 不读取用户的 plugin.msgpackz
  • ❌ 不读取内部 default_env.nu
  • ❌ 不加载用户的 env.nu
  • ❌ 不读取内部 default_config.nu 文件
  • ❌ 不读取用户的 config.nu 文件
  • ❌ 不读取用户的 login.nu 文件
  • ✅ 运行 ls 命令并退出
  • ❌ 不进入 REPL
  • ❌ 不加载 vendor-autoload-dirs 中的文件
  • ❌ 不加载 user-autoload-dirs 中的文件