Skip to content

Commit c5e9d27

Browse files
CornWorldCornWorld
committed
chore: 改进 Makefile 构建体系 + Gitignore 补充
1 parent bae0e6b commit c5e9d27

4 files changed

Lines changed: 179 additions & 7 deletions

File tree

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,9 @@ runtime/core-schema/models.js
2424
# Pack schema artifacts (run scripts/pack-schema-build.mjs <pack> before Go builds)
2525
packs/*/schema.js
2626

27-
# Go build artifact
27+
# Go build artifacts
2828
vault/vanblog
29+
vault/bin/
2930

3031
# pb data (local dev)
3132
pb_data/

‎Makefile‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# ============================================================================
2+
# Vanblog 根 Makefile — 统一的开发/构建入口
3+
#
4+
# 用法:
5+
# make help 显示此帮助
6+
# make dev-go 运行 Go 后端 (开发模式)
7+
# make dev-astro 启动 Astro 前端开发服务器
8+
# make dev 同时启动前后端开发模式
9+
# make build 构建所有产物 (models → Go → Astro)
10+
# make test 运行所有测试
11+
# make vet 运行 Go 静态分析
12+
# make docker 构建生产 Docker 镜像
13+
# make clean 清理构建产物
14+
#
15+
# 不覆盖现有的工具链:
16+
# - vault/Makefile → Go 构建细节委托给 $(MAKE) -C vault
17+
# - vanblog.sh → 部署/运维脚本, 保持独立
18+
# - pnpm scripts → 前端构建保持原样
19+
# ============================================================================
20+
21+
# Source files that feed into models.js (triggers incremental rebuild)
22+
MODEL_SOURCES := $(wildcard sdk/src/models/*.ts)
23+
24+
.PHONY: help dev dev-go dev-astro build build-go build-astro test vet docker clean
25+
# build-models is NOT in .PHONY — it tracks models.js freshness via its prerequisites.
26+
27+
# --- Help ---
28+
29+
help:
30+
@echo "Usage: make <target>"
31+
@echo ""
32+
@echo " dev Run both frontend (Astro) and backend (Go) in dev mode"
33+
@echo " dev-go Run Go backend locally (builds models.js first if missing)"
34+
@echo " dev-astro Start Astro dev server (pnpm dev)"
35+
@echo " build Build all artifacts (models → Go binary → Astro)"
36+
@echo " test Run all tests (Go tests + model type/fixture tests)"
37+
@echo " vet Run go vet ./..."
38+
@echo " docker Build production Docker image (docker buildx)"
39+
@echo " clean Remove all build artifacts"
40+
41+
# --- Development ---
42+
43+
# Generate core schema artifact (incremental — only when sources change)
44+
runtime/core-schema/models.js: $(MODEL_SOURCES)
45+
pnpm build:models
46+
47+
# Run Go backend in dev mode
48+
dev-go: runtime/core-schema/models.js
49+
cd vault && go run . --dev --coreSchemaPath ../runtime/core-schema/models.js
50+
51+
# Start Astro dev server
52+
dev-astro:
53+
pnpm dev
54+
55+
# Run both in parallel (requires two terminals recommended; this uses background)
56+
dev: dev-astro
57+
@echo ""
58+
@echo "ℹ Next: open another terminal and run 'make dev-go' to start the Go backend."
59+
@echo " Astro dev server is running at http://localhost:4321"
60+
61+
# --- Build (production) ---
62+
63+
build-models: runtime/core-schema/models.js
64+
@# models.js is up to date
65+
66+
build-go: build-models
67+
$(MAKE) -C vault build
68+
69+
build-astro:
70+
pnpm --filter vanblog-app build
71+
72+
# Full production build
73+
build: build-models build-go build-astro
74+
@echo "✓ Build complete"
75+
76+
# --- Validation ---
77+
78+
test:
79+
cd vault && go test ./... -count=1
80+
pnpm test:models:types
81+
pnpm test:models:fixtures
82+
83+
vet:
84+
cd vault && go vet ./...
85+
86+
# --- Docker ---
87+
88+
docker:
89+
docker build --target prod -t vanblog:prod .
90+
91+
# --- Clean ---
92+
93+
clean:
94+
$(MAKE) -C vault clean
95+
rm -rf app/dist/
96+
rm -rf sdk/dist/
97+
rm -rf runtime/core-schema/

‎docs/lessons-learned.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -277,3 +277,47 @@ migratecmd.MustRegister(app, app.RootCmd, migratecmd.Config{...})
277277
| ~~外置控制脚本~~ | 已实现(2026-06-28) | 仓库根 `vanblog.sh`,11 项菜单(install/config/start/stop/restart/update/log/backup/restore/maintenance/uninstall)。模板 compose 内嵌脚本,模板更新需重新分发脚本 |
278278
| Caddy admin api 调用方式 | Go 已实现 | routing-strategy.md §9 原计划用 JSVM $http,实际用 Go extend |
279279
| ~~Go markdown 包~~ | 已删除(2026-06-28) | 原本基于 goldmark 的 `internal/markdown` 是死代码,前端 `posts/[id].astro` 改用 marked + DOMPurify 后 Go 端零调用方。删除后 vault 测试全过,go.mod 同步去掉 goldmark 依赖 |
280+
281+
---
282+
283+
## 8. Go 构建产物管理
284+
285+
### 8.1 问题
286+
287+
`go build ./cmd/gw/` 等无 `-o` 的构建命令会在当前目录生成二进制文件。反复运行后会污染工作区，且容易被 `git add -A` 不小心提交。
288+
289+
本项目此前已在以下环节规避了此问题：
290+
291+
| 环节 | 做法 | 状态 |
292+
| ------------------ | ---------------------------------------------------------------------- | -------------------- |
293+
| `vault/Makefile` | `go build -o bin/migrate ./cmd/migrate` + `make build` → `bin/vanblog` | ✅ (2026-07-20 改进) |
294+
| `Dockerfile` | `go build -o /pocketbase .` | ✅ |
295+
| CI (`release.yml`) | `go build -o bin/migrate-$(goos)-$(goarch) ./cmd/migrate` | ✅ |
296+
| `.gitignore` | `vault/vanblog` + `vault/bin/` | ✅ (2026-07-20 补充) |
297+
298+
### 8.2 教训
299+
300+
1. **永远指定 `-o`** — 无论 Makefile 还是手册命令，统一使用 `go build -o bin/<name> ./cmd/<path>`。不要依赖默认行为（二进制丢当前目录）。
301+
2. **产物目录要进 `.gitignore`** — 即使 Makefile 写了 `-o bin/`，如果 `bin/` 没被 gitignore 保护，产物仍可能被提交。`vault/bin/` 就是一个活生生的遗漏。
302+
3. **`go build ./...` 只应在验证编译通过时使用**，不适合日常开发构建。日常开发用 `make` 或 `go build -o`。
303+
4. **Dockerfile 和 CI 必须统一用 `-o`**，不依赖 `WORKDIR` 隐含的当前目录行为——后者可读性差，也容易被目录结构调整破坏。
304+
305+
### 8.3 推荐模式
306+
307+
```makefile
308+
OUTDIR ?= bin
309+
310+
build:
311+
go build -o $(OUTDIR)/vanblog .
312+
313+
migrate:
314+
go build -o $(OUTDIR)/migrate ./cmd/migrate
315+
```
316+
317+
对应 `.gitignore`：
318+
319+
```
320+
# Go build artifacts
321+
vault/vanblog
322+
vault/bin/
323+
```

‎vault/Makefile‎

Lines changed: 36 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,50 @@
1-
.PHONY: migrate migrate-all
1+
OUTDIR ?= bin
2+
LDFLAGS ?= -s -w
3+
CGO ?= 0
4+
5+
.PHONY: help build clean check-models migrate migrate-all \
6+
migrate-linux-amd64 migrate-linux-arm64 migrate-darwin-amd64 migrate-darwin-arm64
7+
8+
# Show available targets
9+
help:
10+
@echo "Usage: make <target>"
11+
@echo ""
12+
@echo " build Build main vanblog binary → $(OUTDIR)/vanblog"
13+
@echo " migrate Build migration CLI → $(OUTDIR)/migrate"
14+
@echo " migrate-all Cross-compile migration CLI for all platforms"
15+
@echo " clean Remove $(OUTDIR)/"
16+
17+
# Check that core schema artifact exists (required before build)
18+
# Path is relative to repo root (../ from vault/), where pnpm build:models outputs.
19+
check-models:
20+
@test -f ../runtime/core-schema/models.js || { \
21+
echo "ERROR: core schema artifact missing. Run 'pnpm build:models' from repo root first."; \
22+
exit 1; \
23+
}
24+
25+
# Build main vanblog binary for current platform
26+
build: check-models
27+
CGO_ENABLED=$(CGO) go build -ldflags="$(LDFLAGS)" -o $(OUTDIR)/vanblog .
228

329
# Build migration CLI for current platform
430
migrate:
5-
CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/migrate ./cmd/migrate
31+
CGO_ENABLED=$(CGO) go build -ldflags="$(LDFLAGS)" -o $(OUTDIR)/migrate ./cmd/migrate
632

733
# Cross-compile for all target platforms (for GitHub Releases)
834
migrate-all: migrate-linux-amd64 migrate-linux-arm64 migrate-darwin-amd64 migrate-darwin-arm64
935

1036
migrate-linux-amd64:
11-
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/migrate-linux-amd64 ./cmd/migrate
37+
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -ldflags="$(LDFLAGS)" -o $(OUTDIR)/migrate-linux-amd64 ./cmd/migrate
1238

1339
migrate-linux-arm64:
14-
GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/migrate-linux-arm64 ./cmd/migrate
40+
GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -ldflags="$(LDFLAGS)" -o $(OUTDIR)/migrate-linux-arm64 ./cmd/migrate
1541

1642
migrate-darwin-amd64:
17-
GOOS=darwin GOARCH=amd64 CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/migrate-darwin-amd64 ./cmd/migrate
43+
GOOS=darwin GOARCH=amd64 CGO_ENABLED=0 go build -ldflags="$(LDFLAGS)" -o $(OUTDIR)/migrate-darwin-amd64 ./cmd/migrate
1844

1945
migrate-darwin-arm64:
20-
GOOS=darwin GOARCH=arm64 CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/migrate-darwin-arm64 ./cmd/migrate
46+
GOOS=darwin GOARCH=arm64 CGO_ENABLED=0 go build -ldflags="$(LDFLAGS)" -o $(OUTDIR)/migrate-darwin-arm64 ./cmd/migrate
47+
48+
# Remove built binaries
49+
clean:
50+
rm -rf $(OUTDIR)/

0 commit comments

Comments
 (0)