debugging-tauri-apps

调试 Tauri 应用程序

本指南介绍如何调试 Tauri v2 应用程序，包括控制台调试、WebView 检查、IDE 配置和 CrabNebula DevTools。

仅开发环境使用的代码

使用条件编译，确保调试代码不会包含在生产构建中：

// Only runs during `tauri dev`
#[cfg(dev)]
{
    // Development-only code
}

// Runtime check
if cfg!(dev) {
    // tauri dev code
} else {
    // tauri build code
}

// Programmatic check
let is_dev: bool = tauri::is_dev();

// Debug builds and `tauri build --debug`
#[cfg(debug_assertions)]
{
    // Debug-only code
}

控制台调试

Rust 打印宏

在运行 tauri dev 的终端中打印消息：

println!("Message from Rust: {}", msg);
dbg!(&variable);  // Prints variable with file:line info

启用回溯

获取详细的错误信息：

# Linux/macOS
RUST_BACKTRACE=1 tauri dev

# Windows PowerShell
$env:RUST_BACKTRACE=1
tauri dev

WebView DevTools

打开 DevTools

• 右键单击并选择“检查元素”
• Ctrl + Shift + i（Linux/Windows）
• Cmd + Option + i（macOS）

平台专用检查器：WebKit（Linux）、Safari（macOS）、Edge DevTools（Windows）。

以编程方式控制

tauri::Builder::default()
    .setup(|app| {
        #[cfg(debug_assertions)]
        {
            let window = app.get_webview_window("main").unwrap();
            window.open_devtools();
            // window.close_devtools();
        }
        Ok(())
    })

生产环境中的 DevTools

创建调试构建以进行测试：

tauri build --debug

若要在生产环境中永久启用 DevTools，请添加到 src-tauri/Cargo.toml：

[dependencies]
tauri = { version = "...", features = ["...", "devtools"] }

WARNING：使用 devtools 功能会启用 macOS 私有 API，导致应用无法通过 App Store 审核。

---

VS Code 设置

必需扩展

扩展	平台	用途
vscode-lldb	全部	LLDB 调试器
C/C++	Windows	Visual Studio 调试器

launch.json 配置

创建 .vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "lldb",
      "request": "launch",
      "name": "Tauri Development Debug",
      "cargo": {
        "args": [
          "build",
          "--manifest-path=./src-tauri/Cargo.toml",
          "--no-default-features"
        ]
      },
      "preLaunchTask": "ui:dev"
    },
    {
      "type": "lldb",
      "request": "launch",
      "name": "Tauri Production Debug",
      "cargo": {
        "args": [
          "build",
          "--release",
          "--manifest-path=./src-tauri/Cargo.toml"
        ]
      },
      "preLaunchTask": "ui:build"
    }
  ]
}

Windows Visual Studio 调试器

若要在 Windows 上更快地调试并获得更好的枚举支持：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch App Debug",
      "type": "cppvsdbg",
      "request": "launch",
      "program": "${workspaceRoot}/src-tauri/target/debug/your-app-name.exe",
      "cwd": "${workspaceRoot}",
      "preLaunchTask": "dev"
    }
  ]
}

tasks.json 配置

创建 .vscode/tasks.json：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "ui:dev",
      "type": "shell",
      "isBackground": true,
      "command": "npm",
      "args": ["run", "dev"]
    },
    {
      "label": "ui:build",
      "type": "shell",
      "command": "npm",
      "args": ["run", "build"]
    },
    {
      "label": "build:debug",
      "type": "cargo",
      "command": "build",
      "options": {
        "cwd": "${workspaceRoot}/src-tauri"
      }
    },
    {
      "label": "dev",
      "dependsOn": ["build:debug", "ui:dev"],
      "group": {
        "kind": "build"
      }
    }
  ]
}

调试工作流

1. 单击 Rust 文件中的行号边栏设置断点
2. 按 F5，或从“运行”菜单中选择调试配置
3. preLaunchTask 会自动运行开发服务器
4. 调试器连接后会在断点处暂停

NOTE：LLDB 会绕过 Tauri CLI，因此必须将 beforeDevCommand 和 beforeBuildCommand 配置为任务。

---

RustRover / IntelliJ 设置

项目配置

如果项目没有顶层的 Cargo.toml，请创建工作区文件：

[workspace]
members = ["src-tauri"]

或者通过 Cargo 工具窗口附加 src-tauri/Cargo.toml。

运行配置

在 运行 | 编辑配置 中创建两个配置：

1. Tauri 应用配置（Cargo）

• 命令：run
• 其他参数：--no-default-features

--no-default-features 标志至关重要——它会告知 Tauri 从开发服务器加载资源，而不是将其打包。

2. 开发服务器配置

对于基于 Node 的项目：

• 创建 npm 运行配置
• 设置包管理器（npm/pnpm/yarn）
• 将脚本设为 dev

对于 Rust WASM（Trunk）：

• 创建 Shell Script 配置
• 命令：trunk serve

调试工作流

1. 先启动开发服务器配置
2. 单击 Tauri 应用配置中的“调试”
3. RustRover 会在 Rust 断点处自动暂停
4. 检查变量并单步执行代码

---

Neovim 设置

必需插件

• nvim-dap - Debug Adapter Protocol 客户端
• nvim-dap-ui - 调试器 UI
• nvim-nio - nvim-dap-ui 的异步依赖
• overseer.nvim（推荐）- 任务管理

先决条件

从 GitHub releases 下载 codelldb，并记下安装路径。

DAP 配置

添加到 Neovim 配置中（init.lua 或等效文件）：

local dap = require("dap")

-- Configure codelldb adapter
dap.adapters.codelldb = {
  type = 'server',
  port = "${port}",
  executable = {
    command = '/path/to/codelldb/adapter/codelldb',
    args = {"--port", "${port}"},
  }
}

-- Launch configuration for Rust/Tauri
dap.configurations.rust = {
  {
    name = "Launch Tauri App",
    type = "codelldb",
    request = "launch",
    program = function()
      return vim.fn.input('Path to executable: ', vim.fn.getcwd() .. '/target/debug/', 'file')
    end,
    cwd = '${workspaceFolder}',
    stopOnEntry = false
  },
}

UI 集成

local dapui = require("dapui")
dapui.setup()

-- Auto-open/close UI
dap.listeners.before.attach.dapui_config = function()
  dapui.open()
end
dap.listeners.before.launch.dapui_config = function()
  dapui.open()
end
dap.listeners.before.event_terminated.dapui_config = function()
  dapui.close()
end
dap.listeners.before.event_exited.dapui_config = function()
  dapui.close()
end

可视化指示器

vim.fn.sign_define('DapBreakpoint', {
  text = 'B',
  texthl = 'DapBreakpoint',
  linehl = '',
  numhl = ''
})
vim.fn.sign_define('DapStopped', {
  text = '>',
  texthl = 'DapStopped',
  linehl = 'DapStopped',
  numhl = ''
})

快捷键

vim.keymap.set('n', '<F5>', function() dap.continue() end)
vim.keymap.set('n', '<F6>', function() dap.disconnect({ terminateDebuggee = true }) end)
vim.keymap.set('n', '<F10>', function() dap.step_over() end)
vim.keymap.set('n', '<F11>', function() dap.step_into() end)
vim.keymap.set('n', '<F12>', function() dap.step_out() end)
vim.keymap.set('n', '<Leader>b', function() dap.toggle_breakpoint() end)
vim.keymap.set('n', '<Leader>o', function() overseer.toggle() end)
vim.keymap.set('n', '<Leader>R', function() overseer.run_template() end)

开发服务器任务

创建 .vscode/tasks.json，以兼容 overseer.nvim：

{
  "version": "2.0.0",
  "tasks": [
    {
      "type": "process",
      "label": "dev server",
      "command": "npm",
      "args": ["run", "dev"],
      "isBackground": true,
      "presentation": {
        "revealProblems": "onProblem"
      },
      "problemMatcher": {
        "pattern": {
          "regexp": "^error:.*",
          "file": 1,
          "line": 2
        },
        "background": {
          "activeOnStart": false,
          "beginsPattern": ".*Rebuilding.*",
          "endsPattern": ".*listening.*"
        }
      }
    }
  ]
}

NOTE：绕过 Tauri CLI 时，开发服务器不会自动启动。请使用 overseer.nvim，或手动启动服务器。

---

CrabNebula DevTools

CrabNebula DevTools 可实时检测应用程序，包括日志检查、性能监控以及 Tauri 事件和命令分析。

功能

• 检查日志事件（包括依赖项日志）
• 监控命令执行性能
• 分析包含负载和响应的 Tauri 事件
• 实时可视化

安装

cargo add [email protected]

设置

尽早在 src-tauri/src/main.rs 中初始化 DevTools：

fn main() {
    // Initialize DevTools only in debug builds
    #[cfg(debug_assertions)]
    let devtools = tauri_plugin_devtools::init();

    let mut builder = tauri::Builder::default();

    #[cfg(debug_assertions)]
    {
        builder = builder.plugin(devtools);
    }

    builder
        .run(tauri::generate_context!())
        .expect("error while running tauri application")
}

使用方法

运行 tauri dev 时，DevTools 会自动打开一个基于 Web 的界面，其中显示：

• 支持筛选的应用程序日志
• 带时间信息的 IPC 命令调用
• 事件负载和响应
• 性能跨度

完整文档请参阅 CrabNebula DevTools 文档。

---

快速参考

任务	命令/操作
启用回溯	RUST_BACKTRACE=1 tauri dev
打开 WebView DevTools	Ctrl+Shift+i / Cmd+Option+i
调试构建	tauri build --debug
添加 DevTools 插件	cargo add [email protected]

IDE 对比

功能	VS Code	RustRover	Neovim
扩展/插件	vscode-lldb	内置	nvim-dap + codelldb
Windows 替代方案	cppvsdbg	内置	codelldb
任务运行器	tasks.json	运行配置	overseer.nvim
设置复杂度	中	低	高

常见问题

1. 断点未命中：构建时确保设置了 --no-default-features
2. 开发服务器未启动：配置 preLaunchTask 或手动启动
3. 应用未加载前端：Tauri 应用启动前，开发服务器必须已运行
4. Windows 枚举显示问题：使用 cppvsdbg 替代 LLDB