diff --git a/README.md b/README.md
index 5af073c..dbb1121 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,24 @@ QML 前端渲染界面，实时显示当前网卡的上行/下行速率与累计
 
 ## 构建与安装
 
-需要配置期存在 `DDEShell` CMake 包（来自 `dde-shell` 开发包）。
+### 构建依赖
+
+构建需要以下开发包：
+
+```sh
+sudo apt install build-essential cmake pkg-config qt6-base-dev qt6-declarative-dev libdtkcommon-dev libdde-shell-dev
+```
+
+各包与 CMake `find_package` 的对应关系：
+
+| 依赖包 | 提供 | 对应 CMake find_package |
+|---|---|---|
+| qt6-base-dev | Qt6 Core / DBus / Network | Qt6 Core DBus Network |
+| qt6-declarative-dev | Qt6 Quick | Qt6 Quick |
+| libdtkcommon-dev | Dtk6 Core | Dtk6 Core |
+| libdde-shell-dev | DDEShell | DDEShell |
+
+> 运行时仅需 `dde-shell` 及 Qt6/Dtk6 运行库，上述 `-dev` 包仅构建时需要。
 
 ### 方式一：从源码安装
 
diff --git a/build-deb.sh b/build-deb.sh
index 5a55452..755435f 100755
--- a/build-deb.sh
+++ b/build-deb.sh
@@ -6,6 +6,25 @@
 
 set -e
 
+# 运行构建步骤：成功时仅显示末尾 3 行，失败时打印完整输出后返回非零
+# 设计原因：原脚本用 | tail -3 管道会吞掉 find_package 等关键错误，
+# 导致缺依赖时用户看不到真正原因（CMake 只在末尾报 Configuring incomplete）
+run_step() {
+    local desc="$1"; shift
+    local log
+    log=$(mktemp)
+    if "$@" > "$log" 2>&1; then
+        tail -3 "$log"
+        rm -f "$log"
+        return 0
+    else
+        echo "错误：${desc}失败，完整输出如下：" >&2
+        cat "$log" >&2
+        rm -f "$log"
+        return 1
+    fi
+}
+
 # 项目根目录
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 cd "$SCRIPT_DIR"
@@ -41,22 +60,43 @@ for cmd in cmake dpkg-deb; do
     fi
 done
 
+echo "[1/6] 检查构建依赖..."
+
+# 检查构建依赖：确认开发包已安装，缺失时提示安装命令并退出
+# 设计原因：用户 clone 后直接运行 build-deb.sh 经常因缺少 -dev 包导致
+# CMake 配置失败，但原脚本用 tail -3 吞掉关键错误，用户无法定位问题。
+# 在构建前主动预检可提前给出明确指引。
+DEPS=(qt6-base-dev qt6-declarative-dev libdtkcommon-dev libdde-shell-dev)
+MISSING=()
+for pkg in "${DEPS[@]}"; do
+    if ! dpkg -s "$pkg" &> /dev/null 2>&1; then
+        MISSING+=("$pkg")
+    fi
+done
+if [ ${#MISSING[@]} -gt 0 ]; then
+    echo "错误：缺少构建依赖包：${MISSING[*]}" >&2
+    echo "请执行以下命令安装：" >&2
+    echo "  sudo apt install ${MISSING[*]} build-essential cmake" >&2
+    exit 1
+fi
+echo "所有构建依赖已就绪"
+
 # 清理并创建构建目录
-echo "[1/5] 构建 CMake 项目..."
+echo "[2/6] 构建 CMake 项目..."
 rm -rf build
-cmake -B build -S . -DCMAKE_BUILD_TYPE=Release 2>&1 | tail -3
-cmake --build build -j"$(nproc)" 2>&1 | tail -3
+run_step "CMake 配置" cmake -B build -S . -DCMAKE_BUILD_TYPE=Release || exit 1
+run_step "CMake 构建" cmake --build build -j"$(nproc)" || exit 1
 
 # 创建 staging 目录（模拟安装根目录）
 STAGE_DIR="$(mktemp -d)"
 trap "rm -rf '$STAGE_DIR'" EXIT
 
-echo "[2/5] 安装到 staging 目录..."
+echo "[3/6] 安装到 staging 目录..."
 # DESTDIR 指定安装根目录前缀，cmake 会将 /usr/... 安装到 $STAGE_DIR/usr/...
-DESTDIR="$STAGE_DIR" cmake --install build 2>&1 | tail -3
+run_step "安装到 staging" env DESTDIR="$STAGE_DIR" cmake --install build || exit 1
 
 # 生成 DEBIAN/control
-echo "[3/5] 生成 control 文件..."
+echo "[4/6] 生成 control 文件..."
 mkdir -p "$STAGE_DIR/DEBIAN"
 
 # 计算安装后大小（KB）
@@ -109,12 +149,12 @@ EOF
 chmod 755 "$STAGE_DIR/DEBIAN/prerm"
 
 # 修正文件权限（so 文件需要 755，qml/json 需要 644）
-echo "[4/5] 修正文件权限..."
+echo "[5/6] 修正文件权限..."
 find "$STAGE_DIR/usr" -type f -name "*.so" -exec chmod 755 {} \;
 find "$STAGE_DIR/usr" -type f \( -name "*.qml" -o -name "*.json" \) -exec chmod 644 {} \;
 
 # 构建 deb
-echo "[5/5] 构建 deb 包..."
+echo "[6/6] 构建 deb 包..."
 rm -f "$DEB_FILE"
 dpkg-deb --build --root-owner-group "$STAGE_DIR" "$DEB_FILE"