diff --git a/local-tool/Makefile b/local-tool/Makefile
index 8a39ec4..2687506 100644
--- a/local-tool/Makefile
+++ b/local-tool/Makefile
@@ -490,7 +490,23 @@ wails-linux: payload-linux ## ⚠️ 必須在 Linux runner 上執行：wails bu
 		echo ""; \
 		exit 1; \
 	fi
-	cd visiona-local && wails build -platform linux/amd64 -clean
+	# webkit2gtk-4.0 從 Ubuntu 22.10+ / Debian 12+ 起被 webkit2gtk-4.1 取代。
+	# 偵測 pkg-config 哪個存在：優先用 4.1（加 -tags webkit2_41），4.0 則
+	# 不加 tag（Wails 預設）。
+	@if pkg-config --exists webkit2gtk-4.1 2>/dev/null; then \
+		echo "==> webkit2gtk-4.1 detected → wails build with -tags webkit2_41"; \
+		cd visiona-local && wails build -platform linux/amd64 -clean -tags webkit2_41; \
+	elif pkg-config --exists webkit2gtk-4.0 2>/dev/null; then \
+		echo "==> webkit2gtk-4.0 detected → wails build (default)"; \
+		cd visiona-local && wails build -platform linux/amd64 -clean; \
+	else \
+		echo ""; \
+		echo "❌ 找不到 webkit2gtk-4.0 或 webkit2gtk-4.1 dev header"; \
+		echo "   請執行：sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev"; \
+		echo "   （舊版 Ubuntu 20.04 可改用 libwebkit2gtk-4.0-dev）"; \
+		echo ""; \
+		exit 1; \
+	fi
 	@du -sh visiona-local/build/bin/visiona-local
 
 # ── 安裝檔打包 ─────────────────────────────────────────────────────
diff --git a/local-tool/scripts/bootstrap-linux.sh b/local-tool/scripts/bootstrap-linux.sh
index 4a2a68b..582b94c 100755
--- a/local-tool/scripts/bootstrap-linux.sh
+++ b/local-tool/scripts/bootstrap-linux.sh
@@ -25,10 +25,22 @@ log "[1/5] 安裝系統套件（需要 sudo）"
 sudo apt update
 sudo apt install -y \
     git curl ca-certificates build-essential pkg-config \
-    libgtk-3-dev libwebkit2gtk-4.1-dev \
+    libgtk-3-dev \
     python3 python3-pip python3-venv \
     file desktop-file-utils fuse libfuse2
 
+# webkit2gtk：優先 4.1（Ubuntu 22.10+ / Debian 12+），退回 4.0（Ubuntu 20.04 / 22.04）。
+# Makefile wails-linux target 會偵測已安裝的版本並自動加 -tags webkit2_41。
+if apt-cache show libwebkit2gtk-4.1-dev >/dev/null 2>&1; then
+    log "  → 偵測到 libwebkit2gtk-4.1-dev 可用，安裝中"
+    sudo apt install -y libwebkit2gtk-4.1-dev
+elif apt-cache show libwebkit2gtk-4.0-dev >/dev/null 2>&1; then
+    log "  → 偵測到 libwebkit2gtk-4.0-dev 可用，安裝中"
+    sudo apt install -y libwebkit2gtk-4.0-dev
+else
+    err "找不到 libwebkit2gtk-4.1-dev 或 libwebkit2gtk-4.0-dev。請手動安裝對應的 webkit2gtk dev package（Ubuntu: sudo apt install libwebkit2gtk-4.1-dev）"
+fi
+
 log "[2/5] 安裝 Go $GO_VERSION"
 if ! command -v go >/dev/null || [[ "$(go version 2>/dev/null)" != *"go$GO_VERSION"* ]]; then
     curl -fsSL "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz" -o /tmp/go.tar.gz