rustaceanvim

<div align="center"> <a href="https://github.com/mrcjkb/rustaceanvim"> <img src="https://yellow-cdn.veclightyear.com/ab5030c0/fd7452de-2556-435f-a3d4-9b046fcbf5df.svg" alt="rustaceanvim"> </a> <a href="./doc/rustaceanvim.txt">浏览文档 »</a> <a href="https://github.com/mrcjkb/rustaceanvim/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml">报告错误</a> · <a href="https://github.com/mrcjkb/rustaceanvim/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.yml">请求新功能</a> · <a href="https://github.com/mrcjkb/rustaceanvim/discussions/new?category=q-a">提问</a> 在<a href="https://neovim.io/">Neovim</a>中提升你的Rust开发体验！ <a href="https://github.com/simrat39/rust-tools.nvim">rust-tools.nvim</a>的高度修改版 🦀

</div>

[!注意]

开箱即用。无需调用setup!

不依赖lspconfig。

设计上采用延迟初始化。

:grey_question: 我需要rustaceanvim吗

如果你刚开始学习Rust，Neovim的内置LSP客户端API (参见:h lsp)或 nvim-lspconfig.rust_analyzer 可能就足够了。它提供了最基本的LSP支持。这个插件是为那些想要额外的非标准功能特定于rust-analyzer的用户设计的。

:pencil: 前提条件

必需

neovim >= 0.10
rust-analyzer

可选

dot来自graphviz，用于绘制crate图。
cargo， Cargo项目需要。
调试适配器(如lldb 或codelldb) 和nvim-dap，用于调试。
Rust的tree-sitter解析器(:Rustc unpretty命令需要)。可以使用nvim-treesitter安装，它还提供高亮等功能。

:inbox_tray: 安装

`rocks.nvim`

:Rocks install rustaceanvim

`lazy.nvim`

{
  'mrcjkb/rustaceanvim',
  version = '^5', -- 推荐
  lazy = false, -- 此插件已经是惰性加载的
}

[!提示]

建议固定到标记的发布版本，以避免破坏性变更。

要手动生成文档，使用:helptags ALL。

Nix

对于启用了flakes的Nix用户，本项目以包和overlay的形式提供输出。它也可在nixpkgs中获得。

查看下面的配置信息以开始使用。

:zap: 快速设置

这个插件自动配置rust-analyzer内置LSP客户端，并与其他Rust工具集成。更多信息请参见使用 / 功能部分。

[!警告]

不要调用nvim-lspconfig.rust_analyzer 的setup或手动设置rust-analyzer的LSP客户端，因为这样做可能会导致冲突。

这是一个开箱即用的文件类型插件，所以不需要调用setup函数或配置任何东西就能让这个插件工作。

你很可能想要添加一些键映射。大多数键映射只在rust文件中有用，所以我建议你在~/.config/nvim/after/ftplugin/rust.lua¹中定义它们

示例：

local bufnr = vim.api.nvim_get_current_buf()
vim.keymap.set(
  "n", 
  "<leader>a", 
  function()
    vim.cmd.RustLsp('codeAction') -- 支持rust-analyzer的分组
    -- 或者如果你不想要分组，可以使用vim.lsp.buf.codeAction()
  end,
  { silent = true, buffer = bufnr }
)

[!TIP]

关于更多与LSP相关的键映射，请参阅nvim-lspconfig的建议。

如果你想与nvim-lspconfig共享键映射，你也可以使用vim.g.rustaceanvim.server.on_attach函数，或者使用LspAttach自动命令。

查看高级配置部分或:h rustaceanvim.config以获取更多配置选项。

[!IMPORTANT]

请不要在after/ftplugin/rust.lua中设置vim.g.rustaceanvim，因为该文件会在插件初始化后才被加载。

:books: 使用方法 / 功能

<details> <summary> 调试 </summary>

debuggables打开一个提示框，让你选择可用的目标。
debug在当前光标位置搜索目标。

:RustLsp[!] debuggables {args[]}?
:RustLsp[!] debug {args[]}?

vim.cmd.RustLsp('debug')
vim.cmd.RustLsp('debuggables')
-- 或者，运行上一个可调试项：
vim.cmd.RustLsp { 'debuggables', bang = true }
-- 或者，覆盖可执行文件的参数：
vim.cmd.RustLsp {'debuggables', 'arg1', 'arg2' }

使用感叹号!调用命令将重新运行最后一个可调试项。

需要：

nvim-dap (请阅读该插件的文档)。
一个调试适配器（例如lldb-dap 或codelldb）。

默认情况下，当LSP客户端连接时，此插件会静默尝试自动加载nvim-dap 配置。加载后，你可以使用require('dap').continue()或:DapContinue调用它们。可以通过设置vim.g.rustaceanvim.dap.autoload_configurations = false来禁用此功能。

:RustLsp debuggables只会加载由rust-analyzer创建的调试配置。
require('dap').continue()将加载所有Rust调试配置，包括在.vscode/launch.json中指定的配置（参见:h dap-launch.json）。
请注意，rustaceanvim可能只能在rust-analyzer完成初始化后加载DAP配置（在大型项目中可能在客户端连接后）。这意味着 DAP配置可能不会在启动时立即加载。

</details> <details> <summary> 可运行项 </summary>

runnables打开一个提示框，让你选择可用的目标。
run在当前光标位置搜索目标。

:RustLsp[!] runnables {args[]}?
:RustLsp[!] run {args[]}?

vim.cmd.RustLsp('run') 
vim.cmd.RustLsp('runnables')
-- 或者，运行上一个可运行项：
vim.cmd.RustLsp { 'runnables', bang = true }
-- 或者，覆盖可执行文件的参数：
vim.cmd.RustLsp {'runnables', 'arg1', 'arg2' }

使用感叹号!调用命令将重新运行最后一个可运行项。

</details> <details> <summary> 可测试项和失败测试诊断 </summary>

如果你使用的是Neovim >= 0.10，你可以将vim.g.rustaceanvim.tools.test_executor 选项设置为'background'，这样插件将在后台运行测试，解析结果，并尽可能将失败的测试显示为诊断信息。

在Neovim 0.9中也可以实现这一点，但测试不会在后台运行，而是会阻塞UI。

:RustLsp[!] testables {args[]}?

vim.cmd.RustLsp('testables')
-- 或者，运行上一个可测试项：
vim.cmd.RustLsp { 'testables', bang = true }
-- 或者，覆盖可执行文件的参数：
vim.cmd.RustLsp {'testables', 'arg1', 'arg2' }

使用感叹号!调用命令将重新运行最后一个可测试项。

</details> <details> <summary> Neotest集成 </summary>

此插件提供了一个neotest适配器，你可以按以下方式将其添加到neotest中：

require('neotest').setup {
    -- ...,
    adapters = {
      -- ...,
      require('rustaceanvim.neotest')
    },
}

注意：如果你使用rustaceanvim的neotest适配器，请不要添加neotest-rust。

以下是rustaceanvim的适配器和neotest-rust的比较：

	rustaceanvim	neotest-rust
测试发现	rust-analyzer (LSP)	tree-sitter
命令构建	rust-analyzer (LSP)	tree-sitter
DAP策略	自动DAP检测（重用`debuggables`）；可通过`vim.g.rustaceanvim.dap`覆盖	默认为`codelldb`；需手动配置
测试运行器	`cargo`或`cargo-nextest`（如果检测到）	`cargo-nextest`
如果您将rustaceanvim配置为使用neotest，对于测试类型的"testables"和"runnables"，`tools.test_executor`将默认使用neotest。

</details> <details> <summary> 递归展开宏 </summary>

:RustLsp expandMacro

vim.cmd.RustLsp('expandMacro')

</details> <details> <summary> 重建过程宏 </summary>

:RustLsp rebuildProcMacros

vim.cmd.RustLsp('rebuildProcMacros')

</details> <details> <summary> 上下移动项目 </summary>

:RustLsp moveItem {up|down}

vim.cmd.RustLsp { 'moveItem',  'up' }
vim.cmd.RustLsp { 'moveItem',  'down' }

</details> <details> <summary> 分组代码操作 </summary>

有时，rust-analyzer会按类别对代码操作进行分组，这不被Neovim内置的vim.lsp.buf.codeAction支持。此插件提供了一个带有UI的命令，可以执行：

:RustLsp codeAction

vim.cmd.RustLsp('codeAction')

如果您将选项vim.g.rustaceanvim.tools.code_actions.ui_select_fallback 设置为true（默认为false），当没有分组代码操作时，它将回退到使用vim.ui.select。

</details> <details> <summary> 悬停操作 </summary>

注意：要激活悬停操作，需要运行命令两次。这会将您移动到窗口中，然后按回车键选择您想要的选项。或者，您可以在配置中将auto_focus设置为true，这样您将自动进入悬停操作窗口。

:RustLsp hover actions

vim.cmd.RustLsp { 'hover', 'actions' }

默认情况下，此插件用悬停操作替换了Neovim的内置悬停处理程序，因此您也可以使用vim.lsp.buf.hover()。

</details> <details> <summary> 范围悬停 </summary>

:RustLsp hover range

vim.cmd.RustLsp { 'hover', 'range' }

</details> <details> <summary> 解释错误 </summary>

在错误诊断上显示一个悬停窗口，其中包含来自rust错误代码索引的解释（如果诊断有错误代码）。

:RustLsp explainError {cycle?|current?}

vim.cmd.RustLsp('explainError') -- 默认为'cycle'
vim.cmd.RustLsp({ 'explainError', 'cycle' })
vim.cmd.RustLsp({ 'explainError', 'current' })

如果使用cycle或无参数调用：类似于vim.diagnostic.goto_next， explainError将从光标位置开始循环诊断，直到找到带有错误代码的诊断。
如果使用current调用：仅在当前光标行搜索诊断。

</details> <details> <summary> 渲染诊断 </summary>

显示一个悬停窗口，其中包含渲染的诊断，如cargo build期间显示的那样。对于解决借用和泛型相关的bug很有用，因为它将重要部分（有时跨文件）整合在一起。

:RustLsp renderDiagnostic {cycle?|current?}

vim.cmd.RustLsp('renderDiagnostic') -- 默认为'cycle'
vim.cmd.RustLsp({ 'renderDiagnostic', 'cycle' })
vim.cmd.RustLsp({ 'renderDiagnostic', 'current' })

如果使用cycle或无参数调用：类似于vim.diagnostic.goto_next， renderDiagnostic将从光标位置开始循环诊断，直到找到带有渲染数据的诊断。
如果使用current调用：仅在当前光标行搜索诊断。

</details> <details> <summary> 打开Cargo.toml </summary>

:RustLsp openCargo

vim.cmd.RustLsp('openCargo')

</details> <details> <summary> 打开docs.rs文档 </summary>

打开光标下符号的docs.rs文档。

:RustLsp openDocs

vim.cmd.RustLsp('openDocs')

</details> <details> <summary> 父模块 </summary>

:RustLsp parentModule

vim.cmd.RustLsp('parentModule')

</details> <details> <summary> 过滤工作区符号搜索 </summary>

rust-analyzer支持过滤工作区符号搜索。

:RustLsp[!] workspaceSymbol {onlyTypes?|allSymbols?} {query?}

vim.cmd.RustLsp('workspaceSymbol')
-- 或
vim.cmd.RustLsp { 
  'workspaceSymbol', 
  '<onlyTypes|allSymbols>' --[[ 可选 ]], 
  '<query>' --[[ 可选 ]], 
  bang = true --[[ 可选 ]]
}

使用感叹号 ! 调用命令将在搜索中包含依赖项。
您还可以通过设置 rust-analyzer 的 workspace.symbol.search 服务器选项来影响 vim.lsp.buf.workspace_symbol() 的行为。

</details> <details> <summary> 合并行 </summary>

将选定的行智能地合并成一行，自动修复空白、尾随逗号和括号。在普通模式下适用于单行，在可视模式下适用于多行。

:RustLsp joinLines

vim.cmd.RustLsp('joinLines')

</details> <details> <summary> 结构化搜索替换 </summary>

在普通模式下搜索整个缓冲区。
在可视模式下搜索选定区域。

:RustLsp ssr {query}

vim.cmd.RustLsp { 'ssr', '<query>' --[[ 可选 ]] }

tty

</details> <details> <summary> 查看 crate 图 </summary>

:RustLsp crateGraph {backend {output}}

vim.cmd.RustLsp { 'crateGraph', '[backend]', '[output]' }

需要：

graphviz 中的 dot

</details> <details> <summary> 查看语法树 </summary>

:RustLsp syntaxTree

vim.cmd.RustLsp('syntaxTree')

</details> <details> <summary> 飞行检查 </summary>

在后台线程中运行 cargo check 或其他兼容命令（如 clippy），并根据命令输出提供 LSP 诊断信息。

在大型项目中很有用，因为每次保存时运行 cargo check 可能会很耗时。

:RustLsp flyCheck {run?|clear?|cancel?}

vim.cmd.RustLsp('flyCheck') -- 默认为 'run'
vim.cmd.RustLsp { 'flyCheck', 'run' }
vim.cmd.RustLsp { 'flyCheck', 'clear' }
vim.cmd.RustLsp { 'flyCheck', 'cancel' }

[!注意]

这只有在设置选项 ['rust-analzyer'].checkOnSave = false 时才有用。

</details> <details> <summary> 查看 HIR / MIR </summary>

打开一个缓冲区，显示光标所在函数的 HIR 或 MIR 的文本表示。对调试或处理 rust-analyzer 本身很有用。

:RustLsp view {hir|mir}

vim.cmd.RustLsp { 'view', 'hir' }
vim.cmd.RustLsp { 'view', 'mir' }

</details> <details> <summary> Rustc 未美化 </summary>

打开一个缓冲区，显示光标附近函数的 MIR 或其他内容的文本表示。实现类似 Rust Playground 的体验。

注意：目前需要 Rust 的 tree-sitter 解析器和 nightly 编译器工具链。

:Rustc unpretty {hir|mir|...}

vim.cmd.Rustc { 'unpretty', 'hir' }
vim.cmd.Rustc { 'unpretty', 'mir' }
-- ...

需要：

Rust 的 tree-sitter 解析器（:Rustc unpretty 命令需要）。可以使用 nvim-treesitter 安装。

</details>

:gear: 高级配置

要修改默认配置，设置 vim.g.rustaceanvim。

查看 :h rustaceanvim 获取所有可用配置选项的详细文档。如果文档尚未安装，您可能需要运行 :helptags ALL。
默认配置可以在这里找到（参见 RustaceanDefaultConfig）。
有关语言服务器配置的详细描述，请参阅 rust-analyzer 文档。

您只需指定想要更改的键，因为未提供的键会应用默认值。

配置示例：

vim.g.rustaceanvim = {
  -- 插件配置
  tools = {
  },
  -- LSP 配置
  server = {
    on_attach = function(client, bufnr)
      -- 您也可以在这里放置键映射
    end,
    default_settings = {
      -- rust-analyzer 语言服务器配置
      ['rust-analyzer'] = {
      },
    },
  },
  -- DAP 配置
  dap = {
  },
}

[!提示]

vim.g.rustaceanvim 也可以是返回表的函数。

使用 `codelldb` 进行调试

对于 Rust，CodeLLDB VSCode 扩展中的 codelldb 提供了比 lldb 更好的体验。如果您使用的发行版允许安装 codelldb 可执行文件，这个插件会自动检测并配置自己使用它作为调试适配器。

一些例子：

NixOS：vscode-extensions.vadimcn.vscode-lldb.adapter
本仓库的 Nix flake 提供了 codelldb 包。
Arch Linux：codelldb-bin（AUR）
使用 mason.nvim： :MasonInstall codelldb 如果你的发行版没有 codelldb 包，你可以按以下方式进行配置：

安装 CodeLLDB VSCode 扩展。
找出它的安装位置。在 Linux 上，通常在 $HOME/.vscode/extensions/ 目录下。
更新你的配置：

vim.g.rustaceanvim = function()
  -- 更新此路径
  local extension_path = vim.env.HOME .. '/.vscode/extensions/vadimcn.vscode-lldb-1.10.0/'
  local codelldb_path = extension_path .. 'adapter/codelldb'
  local liblldb_path = extension_path .. 'lldb/lib/liblldb'
  local this_os = vim.uv.os_uname().sysname;

  -- Windows 上的路径不同
  if this_os:find "Windows" then
    codelldb_path = extension_path .. "adapter\\codelldb.exe"
    liblldb_path = extension_path .. "lldb\\bin\\liblldb.dll"
  else
    -- Linux 上 liblldb 扩展名为 .so，MacOS 上为 .dylib
    liblldb_path = liblldb_path .. (this_os == "Linux" and ".so" or ".dylib")
  end

  local cfg = require('rustaceanvim.config')
  return {
    dap = {
      adapter = cfg.get_codelldb_adapter(codelldb_path, liblldb_path),
    },
  }
end

如何为每个项目动态加载不同的 `rust-analyzer` 设置

默认情况下，这个插件会在项目根目录中查找 rust-analyzer.json² 文件，并尝试加载它。如果文件不存在或无法解码，将使用 server.default_settings。

你可以通过 server.settings 配置来改变这个行为：

vim.g.rustaceanvim = {
  -- ...
  server = {
    ---@param project_root string 项目根目录的路径
    settings = function(project_root)
      local ra = require('rustaceanvim.config.server')
      return ra.load_rust_analyzer_settings(project_root, {
        settings_file_pattern = 'rust-analyzer.json'
      })
    end,
  },
}