Linux 桌面应用打包指南（DEB 格式）— 从源码到 .deb 完整教程

在 Linux 生态中，DEB 包是 Debian/Ubuntu 及其衍生发行版（Deepin、UOS、Kali 等）最主流的软件分发格式。无论你是一个独立开发者想要分发自己的桌面应用，还是企业需要向客户提供内网安装包，掌握 DEB 打包技能都至关重要。

本文将从零开始，手把手教你将一个 Linux 桌面应用打包成标准 DEB 包。内容包括目录结构布局、control 文件编写、preinst/postinst 脚本、图标与菜单注册、dpkg-deb 构建命令，以及如何用 CI 实现自动化打包。

一、DEB 包的核心结构

一个 DEB 包本质上是一个 ar 归档文件（你也可以用 dpkg-deb 来构建）。其内部包含三个要素：

debian-binary — 版本标记文件，内容固定为 2.0
control.tar.gz — 元数据包，含 control、preinst、postinst、prerm、postrm 等
data.tar.gz — 实际文件包，包含你要安装的所有程序文件和目录

但对我们来说，更推荐使用工作目录 + dpkg-deb --build 的方式，这也是社区最常用的方法。

二、准备工作：安装工具

首先确保系统安装了必要的打包工具：

# 安装 dpkg-dev 和构建工具
sudo apt update
sudo apt install -y dpkg-dev build-essential fakeroot lintian

# 验证 dpkg-deb 可用
dpkg-deb --version

lintian 是 Debian 包检查工具，可以帮助发现打包错误。虽然不强制，但强烈建议安装。

三、创建项目目录结构

我们以一个名为 HelloApp 的桌面应用为例。这是一个用 Python + PyQt5 编写的简单工具，包含一个主窗口和系统托盘功能。

首先创建打包所需的目录结构：

# 创建打包工作目录
mkdir -p helloapp-deb/DEBIAN
mkdir -p helloapp-deb/usr/bin
mkdir -p helloapp-deb/usr/share/applications
mkdir -p helloapp-deb/usr/share/icons/hicolor/128x128/apps
mkdir -p helloapp-deb/usr/lib/helloapp

# 目录结构一览
tree helloapp-deb/

一个标准的 DEB 包目录结构如下：

helloapp-deb/
├── DEBIAN/
│   ├── control
│   ├── preinst
│   ├── postinst
│   └── prerm
└── usr/
    ├── bin/
    │   └── helloapp           # 可执行启动脚本
    ├── lib/
    │   └── helloapp/          # 应用实际文件
    │       ├── main.py
    │       ├── ui.py
    │       └── resources/
    └── share/
        ├── applications/
        │   └── helloapp.desktop  # 桌面入口
        └── icons/
            └── hicolor/
                └── 128x128/
                    └── apps/
                        └── helloapp.png  # 图标

四、编写 control 文件

DEBIAN/control 是整个包的"身份证"，包含了包名、版本、依赖关系等核心元数据：

Package: helloapp
Version: 1.0.0-1
Section: utils
Priority: optional
Architecture: amd64
Depends: python3 (>= 3.8), python3-pyqt5, python3-requests
Maintainer: 你的名字 <your@email.com>
Description: HelloApp — 一个简单的桌面应用示例
 HelloApp 是一个基于 PyQt5 的 Linux 桌面工具，
 展示了如何正确打包 DEB 格式的 Linux 桌面应用。
 包含系统托盘、配置窗口等完整功能。

关键字段解析：

Package：包名，全小写，不能有空格
Version：版本号格式 [epoch:]upstream_version[-debian_revision]
Architecture：amd64、i386、arm64 或 all（纯脚本用 all）
Depends：运行时依赖，多个用逗号分隔，支持版本限定（>=、<<）

五、编写维护者脚本

维护者脚本在安装/卸载的不同阶段执行。最常用的是 postinst（安装后执行）和 prerm（卸载前执行）。

postinst — 安装后配置

#!/bin/bash
# DEBIAN/postinst — 安装后执行
set -e

# 更新桌面数据库（让菜单图标生效）
if command -v update-desktop-database > /dev/null 2>&1; then
    update-desktop-database
fi

# 更新图标缓存
if command -v gtk-update-icon-cache > /dev/null 2>&1; then
    gtk-update-icon-cache -f /usr/share/icons/hicolor/ || true
fi

echo "HelloApp 安装完成！请从应用菜单中启动。"

exit 0

prerm — 卸载前清理

#!/bin/bash
# DEBIAN/prerm — 卸载前清理
set -e

echo "正在卸载 HelloApp..."

exit 0

注意：所有维护者脚本都需要赋予执行权限（chmod 755），并且第一行必须是 #!/bin/bash 或 #!/bin/sh。

六、创建 .desktop 桌面入口文件

为了让应用出现在系统菜单中，需要创建 .desktop 文件：

# usr/share/applications/helloapp.desktop
[Desktop Entry]
Type=Application
Name=HelloApp
Name[zh_CN]=你好应用
Comment=A simple Linux desktop application example
Comment[zh_CN]=一个简单的 Linux 桌面应用示例
Exec=/usr/bin/helloapp
Icon=helloapp
Terminal=false
Categories=Utility;Development;
StartupNotify=true

将可执行脚本放到 /usr/bin/ 下：

#!/bin/bash
# usr/bin/helloapp — 启动脚本
cd /usr/lib/helloapp
exec python3 main.py "$@"

七、构建 DEB 包

一切就绪后，构建只是一个命令的事：

# 赋予脚本执行权限
chmod 755 helloapp-deb/DEBIAN/postinst
chmod 755 helloapp-deb/DEBIAN/prerm
chmod 755 helloapp-deb/usr/bin/helloapp

# 构建 DEB 包
fakeroot dpkg-deb --build helloapp-deb

# 输出文件
ls -lh helloapp-deb.deb

上述命令会在当前目录生成 helloapp-deb.deb。包名默认使用目录名，你也可以用 -v 参数指定版本或手动重命名。

生成的包可以用 lintian 检查质量：

lintian helloapp-deb.deb
# 如果没有错误（E:），只有建议（I:）或警告（W:），通常可以接受

八、安装与测试

用 dpkg 命令安装测试：

# 安装
sudo dpkg -i helloapp-deb.deb

# 如果提示缺少依赖，执行
sudo apt-get install -f

# 运行
helloapp

# 卸载
sudo dpkg -r helloapp

如果你已经安装了 helloapp 的旧版本，可以用 --force-overwrite 强制覆盖，或者先删除旧包再安装新版。

九、进阶技巧

1. 使用 debuild / pbuilder 进行完整构建

对于需要上传到 PPA 或官方仓库的包，推荐使用 debuild 和 pbuilder：

# 安装 debhelper
sudo apt install debhelper devscripts

# 创建源码格式的 debian 目录
mkdir helloapp-1.0.0
cd helloapp-1.0.0
dh_make --createorig --single

# 编辑 debian/ 下的文件后构建
debuild -us -uc

2. 多架构支持

如果应用是纯 Python/Shell 脚本，可以将 Architecture 设为 all，一个包即可在所有架构上安装。如果包含二进制文件（如 C/C++ 编译产物），则需要为每种架构单独打包。

3. 配置文件处理

放置在 /etc/ 下的配置文件默认会被 dpkg 保留（升级时不覆盖）。你可以在 control 中用 Conffiles: 字段显式声明：

Conffiles:
 /etc/helloapp/config.ini
 /etc/helloapp/defaults.conf

4. 使用 GitLab CI 自动化打包

# .gitlab-ci.yml 示例
stages:
  - build

deb-build:
  stage: build
  image: ubuntu:22.04
  before_script:
    - apt update && apt install -y dpkg-dev fakeroot python3
  script:
    - chmod 755 DEBIAN/postinst DEBIAN/prerm
    - fakeroot dpkg-deb --build . helloapp-${CI_COMMIT_TAG:-latest}.deb
  artifacts:
    paths:
      - "*.deb"

每次打 Git Tag 时，CI 会自动构建并生成 DEB 包作为构建产物，极大地简化了分发流程。

十、常见问题与排错

问题	原因	解决
`dpkg-deb: error: control directory not found`	DEBIAN 目录名称拼写错误	确认目录名为 `DEBIAN`（全大写）
`package architecture (amd64) does not match system (arm64)`	架构不匹配	修改 Architecture 或使用 `--force-architecture`
`dependency is not satisfiable: python3-pyqt5`	缺少运行时依赖	执行 `sudo apt install -f` 自动补全
应用没有出现在菜单中	.desktop 文件或图标缓存未更新	运行 `sudo update-desktop-database && sudo gtk-update-icon-cache -f /usr/share/icons/hicolor/`
安装后应用打不开	启动脚本缺少执行权限	检查 `/usr/bin/helloapp` 是否有 755 权限

十一、将 DEB 打包应用到你的项目中

掌握了 DEB 打包技术，你就可以将任何 Linux 桌面应用以标准格式分发给用户。这在我们商城中的多个产品中都有实际应用场景：

Codex Desktop Linux 版 — 源码编译的 AI 编程助手，就是通过 DEB 包分发的。用户下载后一条 sudo dpkg -i 命令即可完成安装。
转卡码管理后台客户端 — 我们也提供了 Linux 桌面客户端，打包成 DEB 格式方便服务器运维人员使用。
支付监控工具 — 实时监控多通道支付状态的桌面工具，打包后部署在 Ubuntu 工作站上稳定运行。

如果你想购买已经打包好的 Linux 桌面应用，或者需要源码自行编译打包，欢迎访问源码商城查看更多产品。

总结

本文从最基础的 DEB 包结构讲起，带你一步步构建、安装和测试了一个完整的 Linux 桌面应用 DEB 包。核心要点：

目录结构：DEBIAN/（元数据）+ usr/（实际文件）
control 文件定义包名、版本、依赖等核心信息
postinst/prerm 等维护者脚本处理安装/卸载逻辑
.desktop 文件让应用出现在系统菜单中
fakeroot dpkg-deb --build 构建 DEB 包
使用 CI/CD 可以实现自动化打包发布

打包是 Linux 桌面应用分发的第一公里。掌握它，你的软件就能触及成千上万的 Debian/Ubuntu 用户。