perf(docker): 优化Windows下Docker构建性能

通过为hugo-build服务添加匿名卷挂载/resources和/public目录，避免跨OS文件系统同步大量小文件导致的性能问题。构建时间从超过60秒降至13秒内。

Author: hobbytp

Makefile

@@ -1,4 +1,4 @@
-.PHONY: dev build clean stop optimize-images analyze-performance analyze-content analyze-content-ai full-build full-build-ai validate-architecture generate-covers generate-ai-covers test-covers generate-covers-for-directory ingest-data help
+.PHONY: dev build clean stop optimize-images analyze-performance build-measure analyze-content analyze-content-ai full-build full-build-ai validate-architecture generate-covers generate-ai-covers test-covers generate-covers-for-directory ingest-data help
 
 # Shell 设置
 # 让每个配方(target)的所有命令在同一个 shell 中执行，确保 .env 中的导出变量可在后续命令中生效
@@ -28,6 +28,15 @@ build:
 	@echo "🔨 执行Hugo生产构建..."
 	docker-compose run --rm hugo-build
 
+# 测量构建时间
+build-measure:
+	@echo "⏱️  测量Hugo构建时间..."
+	@start_time=$$(date +%s); \
+	$(MAKE) build; \
+	end_time=$$(date +%s); \
+	duration=$$((end_time - start_time)); \
+	echo "✅ 构建完成，耗时: $${duration} 秒"
+
 # 优化图片
 optimize-images:
 	@echo "🖼️  优化图片资源..."
@@ -288,6 +297,7 @@ help:
 	@echo ""
 	@echo "Build Commands:"
 	@echo "  make build            Execute production build"
+	@echo "  make build-measure    Measure build time"
 	@echo "  make full-build       Full build process (validate + optimize + analyze)"
 	@echo "  make full-build-ai    🤖 AI-enhanced full build process"
 	@echo "  make clean            Clean build files"
@@ -348,3 +358,4 @@ CF_VECTOR_INDEX ?= blog-index
 vectorize-create-category-index:
 	@echo "Creating filterable metadata index 'category' on $(CF_VECTOR_INDEX)"
 	@npx wrangler vectorize create-metadata-index $(CF_VECTOR_INDEX) --property-name=category --type=string
+

README.md

@@ -107,6 +107,24 @@ docker build -t ai-blog .
 docker run -p 1313:1313 ai-blog
 ```
 
+### 使用 Make 运行与构建（推荐）
+
+为确保一致的开发体验并触发必要的验证钩子，建议通过 `make` 管理 Hugo：
+
+```bash
+# 启动开发服务器（如已在运行，先执行 make stop）
+make dev
+
+# 停止已启动的 Hugo 服务
+make stop
+
+# 生产构建（用于部署，包含最完整输出）
+make build
+
+# 查看所有可用命令
+make help
+```
+
 ## 📁 项目结构
 
 ```text
@@ -335,3 +353,4 @@ This project is licensed under the [MIT License](LICENSE), free to use and distr
 **Content Categories**: Paper Reviews, Technical Analysis, Open Source Projects, Industry News, Product Reviews, Celebrity Interviews
 
 ⭐ If this project helps you, please give it a Star for support!
+

docker-compose.yml

@@ -19,6 +19,8 @@ services:
     image: hugomods/hugo:exts-0.152.2
     volumes:
       - .:/src
+      - /src/resources
+      - /src/public
     working_dir: /src
     command: build --minify
     profiles:

docs/issues/2025-12-07-docker-build-performance.md

@@ -0,0 +1,55 @@
+# Docker on Windows 构建性能优化经验 (2025-12-07)
+
+## 问题描述
+
+在 Windows 11 + WSL2/Git Bash 环境下，执行 `make build` (基于 Docker) 极慢，经常超时 (>60s)。
+而同样的 `hugo --minify` 命令在 GitHub Actions Linux 环境下只需几秒钟。
+
+## 根本原因
+
+经过排查，瓶颈在于 **Docker 的文件系统挂载（Bind Mount）机制**。
+
+1.  **原始配置**：
+    `docker-compose.yml` 中的 `hugo-build` 服务仅挂载了根目录 `.:/src`。
+    ```yaml
+    services:
+      hugo-build:
+        volumes:
+          - .:/src
+    ```
+
+2.  **性能杀手**：
+    Hugo 构建时会生成大量静态文件（`/public` 目录，包含数千个文件）和资源文件（`/resources`）。
+    由于 `.:/src` 是一个绑定挂载（Bind Mount），Docker 容器内的每一次写操作都需要同步回 Windows 宿主机的文件系统。
+    在跨操作系统的文件系统（Windows NTFS <-> Linux Container）之间同步大量小文件（I/O 密集型操作）会导致极大的性能开销。
+
+## 解决方案
+
+使用 **匿名卷（Anonymous Volumes）** 来隔离高频写入目录，避免回写到宿主机（如果不需要在宿主机上保留这些构建产物，或者只需要最终结果）。
+
+在 `docker-compose.yml` 中，为 `hugo-build` 服务添加对 `/src/resources` 和 `/src/public` 的挂载：
+
+```yaml
+services:
+  hugo-build:
+    volumes:
+      - .:/src
+      - /src/resources  # 匿名卷，不回写宿主机
+      - /src/public     # 匿名卷，不回写宿主机
+```
+
+## 结果对比
+
+*   **优化前**：构建耗时 > 60s（甚至触发超时），系统卡顿。
+*   **优化后**：构建耗时 < 13s。
+
+## 经验教训
+
+1.  **I/O 敏感性**：Docker on Windows (WSL2 backend) 对跨 OS 的文件系统绑定挂载非常敏感，尤其是涉及大量小文件的读写。
+2.  **构建隔离**：对于中间产物（如 `resources`）或非必须持久化到开发机源码目录的产物（如 `public`，如果是为了部署通常在 CI/CD 中生成），应尽量使用 Docker 内部卷或匿名卷。
+3.  **开发 vs 生产**：开发服务 (`hugo server`) 通常使用内存缓存，对 I/O 不那么敏感，但在 Windows 上也建议对 `resources` 和 `public` 使用匿名卷以提升性能。
+
+## 相关命令
+
+*   `make build`: 生产构建（已优化）。
+*   `make build-measure`: 测量当前构建耗时。

docs/issues/README.md

@@ -0,0 +1 @@
+这里记录开发过程中遇到的一些疑难杂症，和解决方案，以便于日后学习。

scripts/validate-architecture.sh

@@ -158,3 +158,4 @@ else
     echo "   Read ARCHITECTURE.md for guidelines."
     exit 1
 fi
+

static/images/generated-covers/e4d9bfb7b2241da6ed6444aa1df2bdde.webp

@@ -1,6 +1,6 @@
 # Hugo博客性能分析报告
 
-生成时间: 2025-10-31 23:35:02
+生成时间: 2025-12-07 15:47:58
 
 ## 📊 总体统计