Makefile 指南

Makefile 是本项目的任务入口，封装了开发、构建、部署、内容、文档等命令。查看全部目标：

make help

开发与运行¶

命令	作用
`make dev`	Cloudflare Tunnel 增强开发环境（推荐）
`make server`	Hugo 开发服务器（端口 1313，自动后台起文件服务器 8089）
`make stop`	停止所有服务
`make status`	查看服务运行状态
`make tunnel ACTION=status\\|logs\\|stop\\|test`	Cloudflare Tunnel 管理（`tools/tunnel-manager.sh`）

make server 前台跑 Hugo、后台跑文件服务器；make dev 并行前台跑两者，适合调试。

构建与部署¶

命令	作用
`make build`	生产构建（等价 `npm run site:build:production`）
`make build-preview`	预览构建（含 draft/future）
`make deploy-preview`	触发 Cloudflare Pages 预览部署
`make clean`	清理构建产物
`make cache-info` / `make clean-cache`	构建/清理缓存

PDF 导出¶

make pdf BOOK=content/zh/book/envoy-handbook

变量是 BOOK（图书目录）。依赖 tools/pdf-book-exporter（含 CJK 字体与图表渲染支持）。

RAG Worker（向量检索）¶

make rag-upload FILE=path/to/file.md   # 上传单文件向量化
make rag-upload-dir DIR=content/zh     # 递归上传目录
make rag-reindex                       # 重建索引
make rag-verify                        # 校验入库
make rag-deploy                        # 部署 Worker
make rag-test                          # 测试 RAG

详见 AI 聊天机器人（RAG Worker）。

AI 资源与同步¶

命令	作用
`make sync-ai-tags`	同步中文 AI 资源标签到英文
`make sync-ai-oss-rank`	同步 AI OSS Rank 数据
`npm run ai:manifest:generate`	生成 AI 项目清单

图片与内容¶

命令	作用
`make upload-images`	上传图片到 CDN
`make mermaid`	Mermaid 图转 SVG
`npm run content:images:add-dimensions`	给图片加宽高
`npm run content:images:check`	检查图片尺寸完整性
`npm run content:mermaid:transform`	Mermaid 转换

微信发布¶

make wechat-publish       # 发布到微信公众号
make wechat-publish-ai    # 发布 AI 相关内容
make wechat-proxy         # 微信内容代理

文档（本 MkDocs 站）¶

命令	作用
`make docs`	启动 MkDocs 文档服务器
`make docs-build`	构建静态文档
`make validate-docs`	结构化文档校验（`npm run docs:validate`）
`make docs-health`	文档健康检查
`make docs-freshness`	文档新鲜度检查
`make docs-maintenance`	文档维护任务

校验与测试¶

命令	作用
`make check-deps`	检查依赖是否齐全
`make check-built-links`	校验构建产物的链接
`make test` / `make test-fast`	测试套件
`make install`	检查/安装基本依赖

注意事项¶

端口 1313（Hugo）与 8089（文件服务器）需空闲。
日常开发用 make server；调试用 make dev。
停服务优先 make stop 确保彻底退出。
文件服务器用于在网页中点链接直接打开本地源文件。