diff --git a/docker/compose.env.example b/docker/compose.env.example
index 96c66856..8c0cd2b5 100644
--- a/docker/compose.env.example
+++ b/docker/compose.env.example
@@ -83,3 +83,6 @@ CAMOFOX_ACCESS_KEY=
 # TLS_ISSUER=you@example.com
 # TLS_PORT=443
 # TLS_BIND=0.0.0.0
+
+# 构建镜像时的出站代理(可选;直连下载 Deno 运行时可能卡住时填,如经宿主中继 http://172.17.0.1:7891)
+BUILD_PROXY=
diff --git a/docs/plan/lessons.md b/docs/plan/lessons.md
index 3adc64bb..72e483b3 100644
--- a/docs/plan/lessons.md
+++ b/docs/plan/lessons.md
@@ -45,3 +45,4 @@
 28. 一路用 `pkill -f src/main.ts` 收尾，把另一路 worktree 的 API 进程也杀了（命令行相同）→ **规则**：只按自己记下的 pid，或按进程工作目录在本 worktree 下的进程来杀；不要按命令行模糊匹配。
 29. 两路各自合理的改动合起来出问题：B 路以「种子被占用」取消计划，C 路让「取消的计划立即让位」，合并后会取消 → 重评 → 再取消空转 → **规则**：协调者合并时专门看跨线交互（状态取值、原因码、让位 / 重试规则），补一条跨线测试。
 
+30. 发布构建在镜像里下载 Deno 运行时(`dl.deno.land`),构建容器直连外网卡了两个多小时没报错(v0.3.29)→ **规则**:`.env.deploy` 配 `BUILD_PROXY`,`release.sh` 自动带构建代理参数;发布超过 10 分钟没动静先看构建日志卡在哪。
diff --git a/docs/runbook/deploy.md b/docs/runbook/deploy.md
index 9d683568..f340442f 100644
--- a/docs/runbook/deploy.md
+++ b/docs/runbook/deploy.md
@@ -6,6 +6,8 @@ compose 默认有三个服务:`app` + `postgres` + `camofox`(浏览器服务,只
 
 ## 1. 构建镜像
 
+构建阶段会下载 Deno 运行时等外网资源。直连不稳时在 `.env.deploy` 配 `BUILD_PROXY`(如经宿主中继 `http://172.17.0.1:7891`),`deno task release` 会自动带上 `--build-arg HTTP(S)_PROXY`;代理只用于构建,不进镜像。
+
 ```sh
 docker build -t uhd-media-tool:latest .                         # 或 docker compose --env-file .env.deploy build
 APP_VERSION=v0.3.11 docker compose --env-file .env.deploy build app   # 示例:发布时填写对应版本,写进 web 的 version.json
diff --git a/scripts/release.sh b/scripts/release.sh
index ba03cf7b..3de070e0 100644
--- a/scripts/release.sh
+++ b/scripts/release.sh
@@ -63,7 +63,14 @@ set_env SOURCE_REVISION "$head"
 
 if [ $BUILD -eq 1 ]; then
   echo "▶ 构建 uhd-media-tool:$tag"
-  compose build app
+  # 构建阶段要下载 Deno 运行时等外网资源;.env.deploy 配了 BUILD_PROXY 时经它构建(直连可能卡住,见 lessons #30)
+  build_proxy=$(sed -n 's/^BUILD_PROXY=//p' "$ENV_FILE" | tail -1)
+  if [ -n "$build_proxy" ]; then
+    compose build --build-arg HTTPS_PROXY="$build_proxy" --build-arg HTTP_PROXY="$build_proxy" \
+      --build-arg NO_PROXY=localhost,127.0.0.1 app
+  else
+    compose build app
+  fi
 fi
 echo "▶ 替换 app"
 compose up -d --no-deps app