做一个独立站点的成本,不在写代码,在选错架构后 6 个月想搬走。这次没踩到。

起点

目标:单域名,同时跑”作品 + 咨询 + 数字产品 + 文章 + 工具 + 邮件订阅”,中英双语,访客从首页到 Stripe / Creem Checkout 不超过 3 次点击。

听起来朴素,实际上现成工具里没有现成答案 —— Framer / Webflow 写不了支付后端,Next.js Commerce 是给 Shopify 写的,Ghost 是博客不是 storefront。

为什么是 Astro 5

三个原因,排过序:

1. 默认静态。prerender = true 是 opt-out,默认就是静态 HTML。性能、SEO、CDN 缓存,全白送。
2. MDX content collections。内容是 MDX 文件,Zod 校验 schema,build 时 rename 字段会报错。Git 可追踪,导出无成本。
3. Cloudflare Pages 一等公民。@astrojs/cloudflare adapter 输出 workerd bundle,静态 + Functions 同一个部署,免费层够用。

双语怎么搞

/zh/* 和 /en/* 双前缀,getStaticPaths 一次 emit 两个 locale 的页面。src/lib/i18n.ts 暴露 t(lang, key) 函数,所有 UI 文案走这里。

Cookie-based 自动 locale detect 没用 —— 访客第一次来就给个 query param ?lang=en 太粗暴,IP 嗅探不可靠。最终方案:

• 默认 zh(站点主受众)
• <html lang> + 每页 currentPath 推 LocaleSwitcher 算出 counterpart 路径
• LocaleSwitcher 当前语言渲染成 <span aria-current>,另一种语言才是真链接(cf6f868)
• 反向:同 slug 必须在两种语言都存在,否则跳 locale home(避免 404)

3 个月后回头看,这套够用,没出过一次”我点 EN 怎么还是中文”。

Content collections 的好处

5 个集合:products / services / testimonials / articles / now。每个 MDX 文件走 Zod schema 校验,字段错(比如 publishedAt 写成了字符串)build 直接报错。

最大的好处:内容就是 git。我重命名一个产品、删一个评价、合并两个 collection,都是一行 commit。误删能恢复,版本能 diff。Framer / Webflow 给你的是”导出 JSON”,我连导出这一步都省了。

真踩过的坑

坑 1:scoped CSS 漏出。工具页用 document.head.appendChild 注入主题 CSS,Astro 默认把 .classname 编译成 body[data-astro-cid-xxx] .classname 这种 scoped 选择器 —— 但运行时注入的 CSS 不走这个 scope,直接拉宽整个 body。修法:scoped + 把工具预览框包在独立容器里。

坑 2:Locale switcher 死链接。中文按钮 href={currentPath},点了等于跳自己,看起来”没反应”。修法:当前语言改成 <span>,另一种语言才渲染成 <a>。

坑 3:testimonial 全是占位。第一次写 6 条 alice / bob / carol 假评价,代码跑得通,人一看就知道是编的。加 sample: true 字段,渲染时右上角加 SAMPLE / 样本徽章,诚实标出。

每个坑都是 5-30 分钟的 patch,没造成”基础架构重写”。

部署

Cloudflare Pages 接 GitHub,feat/storefront-mvp 分支 push 30 秒后 production 更新。Secrets 走 wrangler pages secret put 或 scripts/upload-secrets.sh 批量上传。KV ×2 + R2 ×1 都是 wrangler.toml 声明,build 时 worker 拿到 Astro.locals.runtime.env。

30 天生产数据:零 downtime、零迁移、零”基础架构再改一次”。

收尾

如果你也想做单域名 storefront,Astro 5 + Cloudflare Pages 是当前最实用的组合 —— 静态 + SSR 同部署、双语、content collections、auth、支付、邮件全栈一个 repo 跑完。

唯一前提:你会写代码。git 是门槛,不是负担。

— 老蔚