Rust在Debian上的图形界面编程教程

在 Debian 系统上用 Rust 做图形界面开发，其实并没有想象中那么复杂。这几年 Rust 的 GUI 生态逐渐成熟，GTK-rs 和 Iced 等库都提供了相当不错的体验。下面就从最基础的环境搭建开始，一步步走通整个流程。

一、环境准备

准备工作其实很简单，主要是两个部分：系统依赖和 Rust 工具链。

安装系统依赖与 Rust 工具链

首先更新软件包索引，然后安装 GTK 3 的开发库——这是 Rust 的 GTK 绑定所必需的：

sudo apt update && sudo apt install -y libgtk-3-dev

接下来安装 Rust，如果还没装过的话：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

安装完成后，重启终端或者执行 source $HOME/.cargo/env 让环境变量生效。

验证安装

用两个命令确认工具链已经就绪：

rustc --version
cargo --version

如果提示命令未找到，多半是 cargo 的 bin 目录没有加入 PATH，检查一下环境变量配置即可。

说明

本教程选择 GTK-rs（gtk4）作为主要方案，原因很简单：它在 Debian 桌面生态中集成度高，文档也比较完善。如果你偏好 Qt，文末会顺带介绍 Qt6 + CXX-Qt 的方案作为参考。

二、快速上手 GTK-rs

创建项目并添加依赖

先创建一个新项目：

cargo new gtk-hello && cd gtk-hello

然后编辑 Cargo.toml，在 [dependencies] 下添加：

gtk = { version = "0.9", features = ["v4_10"] }

最小示例：使用 Application 与 ApplicationWindow

接下来是核心代码，写入 src/main.rs：

use gtk::prelude::*;
use gtk::{Application, ApplicationWindow, Button};

const APP_ID: &str = "com.example.gtk-hello";

fn main() -> glib::ExitCode {
    // 创建应用（GTK 4 推荐基于 Application 的模式）
    let app = Application::builder()
        .application_id(APP_ID)
        .build();

    // 当应用被激活时创建主窗口
    app.connect_activate(|app| {
        let window = ApplicationWindow::builder()
            .application(app)
            .title("Hello, GTK 4")
            .default_width(400)
            .default_height(300)
            .build();

        let button = Button::with_label("Click me!");
        button.connect_clicked(|_| {
            println!("Button clicked!");
        });

        // 将按钮设为窗口的子控件（GTK 4 使用 set_child）
        window.set_child(Some(&button));
        window.present();
    });

    // 运行应用事件循环
    app.run()
}

运行与常见报错

直接用 cargo run 即可运行。如果遇到找不到头文件或链接失败的报错，多半是 libgtk-3-dev 没装好，确认一下这个包是否已安装。在 Debian 上，GTK 4 运行时通常随系统提供，但开发头文件需要从 libgtk-3-dev 获取。

三、常用控件与事件处理

布局与容器

布局方面，最常用的是 gtk::Box。设置方向为 Orientation::Vertical 或 Horizontal，然后用 pack_start 添加子控件并指定伸缩参数，就能实现垂直或水平排列。

按钮与文本框

按钮用 gtk::Button::with_label("...") 创建，通过 connect_clicked 绑定点击事件。文本输入框则是 gtk::Entry，用 get_text() 和 set_text() 来读写内容，非常直观。

对话框

信息提示框可以用 gtk::MessageDialog::new 创建模态对话框，调用 run() 显示，结束后记得 destroy() 清理。

事件处理要点

大多数控件都提供了信号绑定方法，比如 connect_clicked、connect_key_press_event 等。关闭窗口时，可以在 connect_close_request 中返回 Inhibit(true) 并调用 app.quit()，这样能优雅地退出事件循环。

四、打包发布与调试

调试

最直接的调试方式是用 println! 或 eprintln! 输出日志。需要注意的是，GTK 应用在 Wayland 和 X11 下的行为可能有所不同，建议在目标会话中实际测试。如果使用 VS Code 或 CLion 这类 IDE，安装 Rust 插件和 CodeLLDB/LLDB 调试器，就能获得断点调试和变量查看的能力。

打包发布

本地打包很简单，cargo build --release 生成的可执行文件位于 target/release。但分发时需要考虑更多，常用的方案有 Debian 打包或 AppImage。GTK 应用通常需要随应用打包主题与图标资源，或者声明依赖系统主题，否则在用户机器上可能出现界面显示异常。

五、其他 GUI 方案简述

Iced：声明式、跨平台

Iced 受 Elm 架构启发，API 简洁，适合从零构建中小型桌面应用。来看一个最简的骨架示例：

use iced::{Element, Sandbox, Text};

struct App;

impl Sandbox for App {
    type Message = ();

    fn new() -> Self { App }
    fn title(&self) -> String { "Hello, Iced".into() }
    fn update(&mut self, _message: ()) -> iced::Command {
        iced::Command::none()
    }
    fn view(&self) -> Element {
        Text::new("Hello, world!").size(40).into()
    }
}

fn main() -> iced::Result {
    iced::run(App)
}

Qt6 + CXX-Qt：QML 优先

如果你需要 Qt 生态或 QML 的支持，CXX-Qt 是一个不错的选择。它的思路是在 Rust 与 Qt 之间建立安全桥接，QML 负责 UI 层，Rust 实现业务逻辑与属性绑定，两边的优势都能发挥出来。