deb打包：核心+配置+调试全解析

如果你是 Linux 开发者，一定遇到过这样的场景：自己写的程序，发给同事要手动复制文件、配置环境；部署到服务器，还要一步步编译、安装，麻烦到想摆烂。而.deb 包，就是 Debian/Ubuntu 系 Linux 的“安装包天花板”——像 Windows 的.exe、Mac 的.dmg 一样，双击（或一条命令）就能完成安装、配置，分发起来贼方便。

一、为什么要学 deb 打包？Protobuf 为啥选它当案例？

那为啥选 Protobuf 当案例？因为它太典型了！

Protobuf（Protocol Buffers）是 Google 开发的高效序列化工具，比 JSON、XML 更小、更快，是微服务通信、数据存储的“常客”。而且它是 编译型程序（C++开发），和纯脚本工具不同，打包时需要处理编译依赖、动态链接库、多架构适配等 问题；更关键的是，最新版 Protobuf 已推荐使用 CMake 编译（传统 configure 方式仍兼容但非官方首选），吃透它的 CMake 打包流程，以后不管是自己写的 C++程序、还是其他开源项目，打包 deb 都能举一反三。

重点：本次我们打包的是最新版 Protobuf 6.33.5——这个版本刚修复了 CVE-2026-0994 高危漏洞（影响 Python 版 protobuf 包≤6.33.4 版本），且采用官方推荐的 CMake 编译，实操既有实用性，也能掌握“用 CMake 打包修复版开源软件”的技巧，一举两得。

二、基础知识

在动手之前，先搞懂一个核心问题：.deb 包到底是什么？

简单说，deb 包就是一个“压缩包+配置文件”的组合体——它把程序的可执行文件、依赖库、配置文件，按照 Linux 系统的目录规范打包，再加上一套“安装规则”，告诉系统“把什么文件放到什么位置”“需要哪些依赖才能运行”“安装后要做什么”。

举个类比：你要给朋友寄一套组装家具，deb 包就相当于“打包好的家具箱”，里面有：

• 家具零件（可执行文件、依赖库、文档）；
• 组装说明书（debian 目录下的配置文件，告诉系统怎么“组装”安装）；
• 注意事项（依赖要求、版权信息，告诉系统和用户该注意什么）。

而我们打包 Protobuf，本质就是“用 CMake 将 Protobuf 的源码编译成可执行文件，再按照 deb 包的规范，配上‘说明书’，打包成一个能直接安装的文件”。

核心原则：deb 包的目录结构是“硬规矩”，错一个路径，打包就会失败——这也是新手最容易踩的坑，记好这句话：“目录对了，打包就成功了一半”。

三、环境准备

工欲善其事，必先利其器。打包 deb 包，环境必须选对、依赖必须装全，尤其是 Protobuf 已改用 CMake 编译，需额外安装 CMake 相关依赖，否则后续会出现各种“奇奇怪怪”的错误（比如命令找不到、编译失败）。

3.1 首选操作环境

强烈建议在 Debian/Ubuntu 系统中操作（推荐 Ubuntu 20.04/22.04，最稳定），不要在 Windows、Mac 或其他 Linux 发行版（如 CentOS）中操作——跨系统会出现依赖不兼容、目录规范不一致等问题，新手很难排查。

如果没有实体机，用虚拟机、WSL（Windows 子系统）也可以，只要是 Debian/Ubuntu 系统，都能正常操作。

3.2 安装打包核心依赖

打包 deb 包需要用到一系列工具（debhelper、dh-make 等），Protobuf 采用 CMake 编译，需额外安装 CMake 及相关编译依赖，一次性装全，避免后续报错：

# 先更新系统软件源，避免依赖版本过低
sudo apt update && sudo apt upgrade -y

# 安装 deb 打包核心工具
sudo apt install -y debhelper dh-make devscripts build-essential

# 安装 Protobuf 编译依赖（CMake 编译必备，替代原 autoconf/automake）
sudo apt install -y cmake g++ make curl unzip

解释一下关键依赖（重点更新 CMake 相关）：

• build-essential：包含 gcc、g++等编译工具，Protobuf 是 C++开发的，必须装；
• debhelper：deb 打包的“核心工具集”，能自动处理安装、打包流程，简化配置；
• cmake：最新版 Protobuf 官方推荐的编译工具，替代传统 autoconf、automake，核心必备。

3.3 下载最新版 Protobuf 源码

我们打包的是最新版 Protobuf 6.33.5，直接从官方 GitHub 下载源码包（避免用系统自带的旧版本，旧版本可能仍依赖 configure）：

# 下载源码包（6.33.5 版本，修复高危漏洞）
wget https://github.com/protocolbuffers/protobuf/releases/download/v6.33.5/protobuf-all-6.33.5.tar.gz

# 解压源码包（解压后会生成 protobuf-6.33.5 目录）
tar -xvf protobuf-all-6.33.5.tar.gz

# 进入源码目录，后续操作都在这里进行
cd protobuf-6.33.5

这里有个小细节：解压后的目录名是“protobuf-6.33.5”，格式是“包名-版本号”——这是 deb 打包的规范，后续我们会基于这个目录进行操作，不要随意修改目录名。

四、分步实操：从 0 到 1 打包 Protobuf deb 包

这部分是核心，我们分 4 步走：创建标准目录→编写核心配置文件→用 CMake 编译程序→打包生成 deb 包。每一步都配具体命令和解释，新手也能轻松跟上，重点替换原 configure 编译方式为 CMake。

4.1 第一步：创建 deb 打包的标准目录结构

deb 包有严格的目录规范，核心是“在源码目录下创建 debian 目录”，所有配置文件都放在这个目录里。结合 Protobuf 的特点，我们的目录结构如下（重点记 debian 目录和 usr 目录）：

protobuf-6.33.5/          # 项目根目录（源码目录，已存在）
├── debian/             # 核心配置目录（必须叫 debian，手动创建）
│   ├── changelog       # 版本更新日志（必填，告诉系统版本信息）
│   ├── control         # 包信息核心文件（必填，最关键）
│   ├── copyright       # 版权信息（必填，开源软件必须有）
│   ├── rules           # 编译/安装规则（必填，重点修改为 CMake 编译）
│   ├── compat          # 兼容版本（必填，简单填个值即可）
│   └── install         # 定义文件安装路径（可选，这里我们需要配置）
└── usr/                # 模拟系统目录（手动创建，存放编译后的文件）
    ├── bin/            # 可执行文件目录（对应系统/usr/bin，放 protoc 编译器）
    ├── lib/            # 动态链接库目录（对应系统/usr/lib，放 Protobuf 的库文件）
    └── share/
        └── doc/
            └── protobuf/  # 文档目录（放 README、版权说明等）

新手不用手动一个个创建目录，我们用 dh-make 工具自动生成模板，再手动修改，效率更高：

# 在 protobuf-6.33.5 目录下，生成 debian 目录模板
dh_make -s -n --createorig

# 提示选择包类型时，输入 s（single binary，单二进制包），回车即可
# 生成后会有很多多余的示例文件，删除它们，避免干扰
rm debian/*.ex debian/*.EX debian/README.*

执行完上面的命令，debian 目录就创建好了，接下来我们逐一编写里面的核心配置文件——这是打包的“灵魂”，重点修改 rules 文件的编译规则，适配 CMake。

4.2 第二步：编写 debian 目录下的核心配置文件（重点中的重点）

debian 目录下有 5 个核心文件，我们按“从简单到复杂”的顺序编写，每个文件都配 Protobuf 专属示例（重点更新 control 依赖和 rules 编译规则），复制后修改少量内容即可使用。

1. compat：兼容版本

这个文件用来指定 debhelper 的兼容版本，Ubuntu 20.04+兼容版本 12，直接写 12 即可：

12  # 兼容 debhelper 12 版本，Ubuntu 20.04+通用

2. control：包信息核心文件（最关键）

这个文件相当于 deb 包的“身份证”，包含包名、版本、依赖、描述等信息，重点更新 Build-Depends，删除原 autoconf/automake 依赖，添加 cmake 依赖，Protobuf 的 control 文件示例如下（复制到文件中，修改括号里的内容即可）：

Source: protobuf                # 源码包名（小写，无空格，和项目名一致）
Section: utils                 # 包分类（utils=工具类，合适）
Priority: optional             # 优先级（optional 即可，非必需包）
Maintainer: 你的名字 <你的邮箱>  # 替换成你的信息（比如：Zhang San <zhangsan@163.com>）
Build-Depends: debhelper-compat (=12), cmake, g++  # 构建依赖（更新为 CMake，删除 autoconf/automake）
Standards-Version: 4.6.2       # 标准版本（固定值，不用改）
Homepage: https://github.com/protocolbuffers/protobuf  # Protobuf 官方地址，不用改
Package: protobuf              # 最终 deb 包名（和 Source 一致即可）
Architecture: amd64            # 架构（Protobuf 是编译型 C++程序，不能用 all，填 amd64，对应 64 位系统）
Depends: ${shlibs:Depends}, ${misc:Depends}, libc6  # 运行依赖（系统基础库，必须有）
Description: Google Protocol Buffers (latest version 6.33.5)  # 简短描述（1 行）
  Protocol Buffers is a language-neutral, platform-neutral, extensible method
  for serializing structured data, developed by Google. This package contains
  the latest version 6.33.5, which fixes the high-risk vulnerability CVE-2026-0994.
  It includes the protoc compiler and related libraries for C++ development,
  compiled with CMake (official recommended build tool).
  # 详细描述（开头必须空格，可多行，新增 CMake 编译说明）

重点注意 3 个坑（新手必看，新增 CMake 相关）：

• Architecture：Protobuf 是编译型程序，不能填 all（all 是跨架构，适合纯脚本），64 位系统填 amd64，32 位填 i386；
• Build-Depends：必须包含 cmake 依赖（最新版 Protobuf 编译核心），删除原 autoconf、automake、libtool，少一个就会编译失败；
• Description：详细描述开头必须有空格，否则打包会报错（Debian 的硬性规范），可新增 CMake 编译说明，贴合最新实操。

3. changelog：版本更新日志（必填，格式不能错）

这个文件记录版本更新信息，系统会根据它识别版本号，新手建议用 dch 命令自动生成，避免手动写格式错误，可新增 CMake 编译说明：

# 自动生成 changelog 文件（参数解释：-v 版本号，--package 包名，后面是更新说明）
dch --create -v 6.33.5-1 --package protobuf "Initial release: Protobuf 6.33.5, fix CVE-2026-0994 vulnerability, compiled with CMake (official recommended)."

执行完命令后，会自动打开编辑器，确认内容如下（无需修改，直接保存退出即可）：

protobuf (6.33.5-1) unstable; urgency=medium
  * Initial release: Protobuf 6.33.5, fix CVE-2026-0994 vulnerability, compiled with CMake (official recommended).
 -- 你的名字 <你的邮箱>  Fri, 27 Feb 2026 10:33:00 +0800

格式说明：版本号是“6.33.5-1”（主版本-修订号），后面是更新说明（新增 CMake 编译标注），最后是维护者信息和日期，自动生成的格式完全符合规范，不用手动修改。

4. rules：编译/安装规则

这个文件是“编译和安装的指挥手册”，告诉系统“如何用 CMake 编译 Protobuf 源码”“编译后的文件放到哪里”。由于我们替换为 CMake 编译，需彻底修改编译步骤，替换原 configure 相关命令：

#!/usr/bin/make -f
# 定义 CMake 编译步骤
override_dh_auto_configure:
    mkdir -p build && cd build && cmake .. -DCMAKE_INSTALL_PREFIX=/usr  # 创建 build 目录，指定安装前缀为/usr

override_dh_auto_build:
    cd build && make -j4  # 进入 build 目录编译，-j4 表示用 4 个线程，加快编译速度（根据 CPU 核心数调整）

override_dh_auto_install:
    cd build && make install DESTDIR=$(CURDIR)/debian/protobuf  # 安装到 debian/protobuf 目录，自动映射到系统目录

# 通用规则，dh 工具自动处理后续打包流程
%:
    dh $@

写完后，必须给 rules 文件添加执行权限，否则打包时会提示“权限不足”：

chmod +x debian/rules

关键解释（CMake 核心）：

1. mkdir -p build：CMake 编译需单独创建 build 目录（规范操作，避免源码目录混乱）；
2. -DCMAKE_INSTALL_PREFIX=/usr：指定安装路径，和我们创建的 usr 目录对应，打包时自动识别；
3. 所有编译、安装命令均在 build 目录下执行，符合 CMake 编译规范。

5. copyright：版权信息（必填，开源软件必须有）

Protobuf 是开源软件，遵循 BSD 3-Clause 许可证，我们直接复制以下内容，修改维护者信息即可（无需修改，与编译方式无关）：

Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Upstream-Name: protobuf
Upstream-Contact: Google Inc. <protobuf@google.com>
Source: https://github.com/protocolbuffers/protobuf
Files: *
Copyright: 2008-2026 Google Inc.
License: BSD-3-Clause
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are
 met:
 .
 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
 2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.
 3. Neither the name of Google Inc. nor the names of its contributors
    may be used to endorse or promote products derived from this software
    without specific prior written permission.
 .
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

注意：如果是自己的程序，版权信息可以填自己的，但开源软件必须遵循其原始许可证，不能随意修改。

6. install：定义文件安装路径（可选，但建议配置）

这个文件用来明确“哪些文件安装到系统的哪个位置”，Protobuf 我们配置如下，确保可执行文件、库文件、文档都能正确安装（与编译方式无关，无需修改）：

usr/bin/protoc /usr/bin/
usr/lib/* /usr/lib/
usr/share/doc/protobuf/* /usr/share/doc/protobuf/

格式：左边是我们目录下的文件路径，右边是系统中的安装路径，中间用空格分隔。

4.3 第三步：用 CMake 编译 Protobuf 源码（打包前的关键一步）

配置文件写好后，我们先手动用 CMake 编译一次 Protobuf，确认编译无错误，再进行打包——这样可以提前排查编译相关的问题，避免打包时出错，步骤与 rules 文件中的编译流程一致：

# 在 protobuf-6.33.5 目录下，执行 CMake 编译命令（与 rules 文件一致）
mkdir -p build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/usr
make -j4

编译需要几分钟（根据 CPU 性能而定），如果没有报错，说明编译成功；如果报错，大概率是依赖缺失，回去检查 3.2 节的依赖（重点确认 cmake 是否安装）。

4.4 第四步：打包生成 deb 包（最终一步，见证奇迹）

编译成功后，回到 protobuf-6.33.5 目录（退出 build 目录），执行打包命令，新手无需签名（签名需要证书，麻烦），用-us -uc 参数跳过签名：

cd ..  # 退出 build 目录，回到 protobuf-6.33.5 根目录
dpkg-buildpackage -us -uc

打包过程会自动执行 CMake 编译、安装、打包流程，耐心等待 1-2 分钟，只要没有出现“error”（错误），只有“warning”（警告），就说明打包成功。

打包成功后，生成的 deb 包会在上级目录（protobuf-6.33.5 的上一级目录），文件名格式如下：

protobuf_6.33.5-1_amd64.deb  # 包名 _ 版本号 _ 架构.deb，和我们配置的一致

同时还会生成.dsc、.tar.xz 等辅助文件，这些文件是源码包相关的，我们不用管，重点关注.deb 文件即可。

五、深度解析：deb 打包描述文件的“底层逻辑”（老手进阶）

新手跟着上面的步骤，能成功打包 Protobuf，但要想真正掌握 deb 打包，还要理解核心配置文件的“底层逻辑”——尤其是 CMake 编译对应的配置，知道每个文件的作用，才能应对不同程序的打包需求。

5.1 核心配置文件的作用总结（一张表看懂，更新 CMake 相关）

5.2 编译型程序 vs 纯脚本程序，打包差异（关键区别）

我们之前用“自定义脚本”举例，现在用 Protobuf（CMake 编译型）举例，两者的打包差异主要在 3 点，新手容易混淆，记好：

• 架构（Architecture）：纯脚本程序填 all（跨架构），编译型程序填具体架构（如 amd64）；
• rules 文件：纯脚本程序用最简规则（dh $@），编译型程序（CMake）需要自定义编译步骤（创建 build 目录、cmake 配置、make 编译）；
• 依赖：编译型程序（CMake）需要添加“构建依赖”（如 cmake、g++），纯脚本程序只需添加“运行依赖”（如 bash、python）。

六、问题排查与调试：打包失败？这样解决

新手打包时，大概率会遇到报错，不用慌——90%的错误都是“路径错、依赖缺、格式错”，结合 Protobuf 的 CMake 编译特点，我们补充 CMake 相关报错，教你如何排查和调试。

6.1 常见错误及解决方案

错误 1：打包时提示“依赖未满足”（最常见）

报错示例 1（旧依赖缺失）：dpkg-checkbuilddeps: error: Unmet build dependencies: autoconf automake

报错示例 2（CMake 依赖缺失）：dpkg-checkbuilddeps: error: Unmet build dependencies: cmake

原因：control 文件中的 Build-Depends 配置错误，要么残留旧的 autoconf/automake 依赖，要么缺少 cmake 依赖，或系统中未安装对应依赖。

解决方案：

• 检查 3.2 节的依赖是否装全，缺失 cmake 用 sudo apt install -y cmake 安装，删除系统中多余的 autoconf/automake（可选）；
• 检查 control 文件的 Build-Depends，确保只包含 cmake、g++，删除 autoconf、automake、libtool。

错误 2：编译失败，提示“cmake: command not found”

原因：没有安装 cmake 依赖，Protobuf 的 CMake 编译无法执行（最新版核心报错）。

解决方案：sudo apt install -y cmake，安装后重新编译。

错误 3：打包成功，但安装时提示“无法定位软件包”或“架构不匹配”

原因：Architecture 配置错误（比如填了 all，而 Protobuf 是编译型程序），或者 deb 包的架构和系统架构不匹配。

解决方案：

• 修改 control 文件的 Architecture，64 位系统填 amd64，32 位填 i386；
• 重新打包，确保 deb 包的架构和系统架构一致（用 uname -m 命令查看系统架构）。

错误 4：打包时提示“Description 详细描述开头没有空格”

原因：control 文件的 Description 详细描述，每一行开头没有加空格，违反 Debian 规范。

解决方案：编辑 control 文件，在详细描述的每一行开头加一个空格，保存后重新打包。

错误 5：安装后，运行 protoc 提示“command not found”

原因：install 文件配置错误，protoc 没有安装到/usr/bin 目录，或者权限不足。

解决方案：

• 检查 install 文件，确保有“usr/bin/protoc /usr/bin/”这一行；
• 检查 protoc 文件的权限，确保有执行权限（chmod +x usr/bin/protoc）；
• 重新打包、安装，用 which protoc 命令验证（输出/usr/bin/protoc 即为成功）。

错误 6：CMake 编译报错“No such file or directory: build”

原因：rules 文件或手动编译时，未提前创建 build 目录，CMake 无法生成编译文件。

解决方案：手动创建 build 目录（mkdir -p build），再执行 cmake 命令；或检查 rules 文件，确保 override_dh_auto_configure 中包含 mkdir -p build。

6.2 deb 包调试技巧（老手必备）

如果打包成功，但安装或运行有问题，用以下 3 个技巧调试，快速定位问题：

技巧 1：用 lintian 检查 deb 包的合法性

lintian 是 deb 包检查工具，能检测出包的配置错误、格式问题，新手打包后一定要用它检查：

# 进入 deb 包所在目录，执行检查命令
lintian protobuf_6.33.5-1_amd64.deb

结果解读：无“E”（error，严重错误）即可，“W”（warning，警告）可忽略，警告大多是格式细节问题，不影响使用。

技巧 2：解压 deb 包，查看内部结构

如果安装后文件路径不对，可以解压 deb 包，查看内部文件是否按预期放置：

# 创建一个临时目录，解压 deb 包
mkdir -p deb-test && cd deb-test
dpkg-deb -x ../protobuf_6.33.5-1_amd64.deb .

解压后，会看到 usr、debian 等目录，检查usr/bin、usr/lib下是否有对应的文件，就能判断路径是否正确。

技巧 3：用 dpkg -i –debug=help 调试安装过程

如果安装时报错，但不知道原因，可以用调试模式安装，查看详细的安装日志：

sudo dpkg -i --debug=all protobuf_6.33.5-1_amd64.deb

日志会详细显示“哪个文件安装失败”“哪个依赖缺失”，根据日志提示排查问题即可。

七、总结：吃透这 3 点，打包任何 deb 包都不怕

通过打包最新版 Protobuf（CMake 编译），我们从新手入门到老手进阶，完整掌握了 deb 打包的流程，结合官方最新规范，核心就 3 点，记好就能举一反三：

1. 目录规范是基础：必须有 debian 目录，usr 目录的结构要和系统目录一致，错路径必失败；
2. 配置文件是核心：control（填对 CMake 相关依赖和架构）、rules（写对 CMake 编译规则）、changelog（格式正确+标注 CMake），这 3 个文件搞定，打包就成功了 80%；
3. 调试技巧是保障：打包失败查依赖（重点查 cmake）、路径、格式，安装失败用 lintian、解压、调试模式，快速定位问题。

本次打包的 Protobuf 6.33.5，采用官方推荐的 CMake 编译方式，不仅能直接安装使用（修复了高危漏洞），还能作为 CMake 编译型程序打包的模板，以后不管是打包自己的 C++程序、还是其他开源项目，都能直接参考本次的配置。

如果你的程序是其他类型（如 Python 脚本、Go 二进制、GUI 程序），可以留言告诉我，我会针对性调整打包配置~

以上关于deb打包：核心+配置+调试全解析的文章就介绍到这了，更多相关内容请搜索码云笔记以前的文章或继续浏览下面的相关文章，希望大家以后多多支持码云笔记。