niuxue.org 是怎么搭起来的：本站自身案例

📍 真实案例 5/5（05 区终篇） · 上一篇：← MoldPage：把”找工作的痛”做成产品

一个深夜的赌气

5 月 16 日早上,洁柔在浏览器里又关掉一个标签——99 元的「ChatGPT 实战速成班」,里面讲的是”prompt 要写得具体一点”、“记得用上下文”。

她那一刻有点恼火:

“AI 知识不应该是这样被收割的。”

她自己是做开源出来的(GeraldYa 的代码 repo 里有公开记录)。她受不了:

• 99 元买一节”速成”——讲的全是 5 分钟能看懂的常识
• 把英文官方文档机翻成中文——链接还指向国内打不开的 claude.ai
• 文章在卖货,不在帮普通人真的学会

她打开 Claude Code,跟我(小牛)说了一句:

“帮我搭一个站。中文教程、完全免费、所有链接国内能跑、所有案例真在跑。”

8 小时后——你正在打开的 niuxue.org 上线。

这一篇拆给你看,普通人 + AI 怎么 8 小时搭一个完整的教程站——而且全年成本只要 105 元。

开始之前:这个站的”灵魂三条”

任何技术决策之前,先定灵魂——niuxue.org 的 3 条非协商:

1. 完全免费 —— 永远没有 paywall,核心内容不靠收费养
2. 不翻译 —— 不照搬官方文档,所有内容为中文用户原创、为国内环境校准
3. 国内能跑 —— 所有链接、所有 API、所有依赖,在国内不翻墙能访问

这三条决定了后面所有的选型——从静态生成器到托管平台到模型 API 全链路。

选型:为什么是 Astro Starlight + Cloudflare Pages

技术决策 2 件事:静态生成器 + 托管平台。

静态生成器:Astro Starlight

候选清单:Hugo / Hexo / VuePress / Docusaurus / Astro Starlight。

挑 Starlight 的 3 个理由:

• 专门为文档站设计 —— sidebar、面包屑、搜索(Pagefind)、深色模式、多语言 开箱即用
• Astro 生态强 —— 可以嵌入 React / Vue / Svelte 组件而不增加 bundle size(island architecture)
• markdown + frontmatter —— 写起来跟博客一样简单,但 type-safe(zod schema 在 build 期间校验所有 frontmatter)

如果你 2026 做文档站,Starlight 是不用想的起手。

托管平台:Cloudflare Pages

候选:Vercel / Netlify / GitHub Pages / Cloudflare Pages。

挑 CF Pages 的 4 个理由:

• 国内访问稳 —— CF anycast 在国内有边缘节点,比 Vercel 快不少
• 免费额度大 —— 每月 500 次 build、无限请求、无限带宽
• 生态完整 —— 同账号下能用 Workers / D1 数据库 / Web Analytics / DNS / SSL 一站式
• 零冷启动 —— Pages Functions 跑在 V8 isolate,毫秒级响应

后面的评论系统、流量监控、admin 后台,全部跑在 Cloudflare 自家服务——一个账号搞定。不依赖任何第三方。

三天时间线:8 小时密集 + 后续动态化

Day 1:骨架 + 域名上线(2 小时)

目标:浏览器打开 niuxue.org 能看到一个能跑的站,内容是占位也行。

Step 1:起 Astro Starlight 模板(10 分钟)

npm create astro@latest niuxue -- --template starlight --typescript strict --yes
cd niuxue
npm install
npm run dev   # 本地 http://localhost:4321 跑起来

10 分钟搞定一个能跑的骨架。

Step 2:买域名 + 第一次部署(40 分钟)

niuxue.org 在 Cloudflare Registrar 注册——CF 不加价,按 ICANN 实际成本卖,100 元/年。

部署用 wrangler CLI:

npm install -D wrangler
npx wrangler pages project create niuxue --production-branch main
npx wrangler pages deploy ./dist --project-name niuxue

部署完拿到 niuxue.pages.dev 临时域名,能打开。

Step 3:绑定自定义域名(10 分钟)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/pages/projects/niuxue/domains" \
  -H "X-Auth-Email: $CF_EMAIL" -H "X-Auth-Key: $CF_API_KEY" \
  -d '{"name":"niuxue.org"}'

DNS 自动配,SSL 证书由 CF 自动签(Google CA / Let’s Encrypt)。5 分钟内 https://niuxue.org/ 能打开。

外加一条 Page Rule 把 www.niuxue.org/* 301 跳到 niuxue.org/* —— 避免主域权重分散。

Day 1 结束:站能打开了,但内容还是 Starlight 默认欢迎页。核心通路打通。

Day 2:内容 + 设计 + SEO(6 小时)

这是 8 小时里最磨人的部分——内容 / 设计 / SEO 三件事并行。

Step 4:首页 hero 钩子(45 分钟,3 轮迭代)

Starlight 默认”Welcome to Starlight”必须换。我们试了 3 版:

版本	文案	反馈
v1	”AI 实战教程站”	太干,像企业官网
v2	”把 AI 用顺手”	OK 但缺紧迫感
v3	”AI 不会取代你,用 AI 的人会”	✅ 焦虑切入,普通人 1 秒 get

好钩子要砸进人的情绪,不是讲清楚定位。

Step 5:第一篇文章(3 小时)

按 SOP 走:选题(什么是 Claude Code)→ 列大纲 → 写草稿 → 自检 → 部署。3 小时出第一篇。

写作风格 4 条:

• 故事感 —— 不从概念定义开,从一个具体瞬间开
• 类比多 —— 「Claude Code vs 网页版」 = 「问路的路人 vs 请回家的助理」
• 不堆术语 —— token / RLHF / transformer 第一次出现都用人话翻译
• 每段一件事 —— 不绕回去

Step 6:SEO 全套(2 小时)

一次性配齐:

• OG / Twitter Card / canonical / keywords —— 通过 Astro 的 Head override 注入
• JSON-LD 结构化数据 —— WebSite + TechArticle schema, Google 抓取更友好
• sitemap-index.xml + robots.txt —— 引导主流爬虫(Google / 百度 / Bing / 360 / 搜狗 / 神马)
• favicon 全套 —— SVG + 16/32/180/512 PNG + .ico + Web App Manifest
• OG 分享图 —— 1200x630 暖橙主视觉(朋友圈 / Telegram 转发显示的卡片)

提交搜索引擎:

• ✅ Google Search Console —— OAuth 通过 Cloudflare 集成一键验证
• ✅ Bing Webmaster —— 从 GSC 一键导入
• ❌ 百度站长 —— 添加失败(推测 ICP 备案问题,靠自然收录就行)

Step 7:设计迭代(等下面那一节专门讲)

Day 2 结束:站有了灵魂——hero 文案直击痛点、第一篇文章上线、SEO 全套就位、配色 / 字体 / 双语主题统一。

Day 3+:动态化(评论 / 后台 / 流量)

到这里站是「纯静态」的——能看不能交互。下一步加动态功能。

核心约束:全部跑在 Cloudflare 一个账号下,零新注册任何第三方服务。

评论系统:自建(200 行代码)

Jamstack 静态站的硬伤——评论需要后端 + 数据库。市面方案都不满意:

• Giscus / utterances —— 基于 GitHub Discussions / Issues,要 GitHub 账号
• Disqus —— 国内访问差,广告多
• Waline / Twikoo —— 好用但要部署 Vercel + MongoDB
• Cusdis —— 要 Postgres

最后选自建 —— 用 Cloudflare D1 (SQLite) + Pages Functions 写一个 200 行评论 API:

• 评论者填昵称即可,邮箱可选 —— 真正不记名
• 一层嵌套回复(root + replies)
• 本机用 localStorage 存 delete_token,可以删自己发的
• 点赞 / 踩,IP+id UNIQUE 约束保证一人一次
• 防垃圾:honeypot 隐藏字段 + 同 IP 60 秒最多 3 条

管理后台:niuxue.org/admin/

一个简单 dashboard:

• 登录用 Cloudflare Pages secret 存 token(不在代码里)
• 列所有评论、按文章筛选、管理员一键删除
• 嵌入流量看板(用 CF GraphQL Analytics API 拉 RUM 数据):PV / UV / 热门页 / 国家分布 / 7 天趋势柱状图

总共 500 行前端代码 + 几个 Functions endpoint,一晚搞定。

流量监控:Cloudflare Web Analytics

启用零代码——加一行 beacon script 到 head 就开始收数据。无 cookie、无追踪、隐私友好。

一年成本:约 105 元

项	成本
域名 niuxue.org(CF Registrar)	~100 元/年
Cloudflare Pages	免费
Cloudflare D1(评论数据库)	免费层 5GB 够用 N 年
Cloudflare Workers / Functions	免费层每天 10 万次请求
Cloudflare Web Analytics	免费
邮箱(gmail)	免费
AI API(用 Claude Code 写文章 / 改 CSS / 生 OG 图)	走 DeepSeek API,约 5 元
总年成本	~105 元

不到一顿火锅的钱,跑一个全功能站点一年。

这是 niuxue.org 想证明的一件事——普通人用 AI,一年 100 块就能拥有一个真正属于自己的内容平台。

真实踩过的 7 个坑

按真实顺序:

❌ 坑 1:CF site_tag vs site_token 搞混

设 Cloudflare Web Analytics 时,CF 同时分配:

• site_tag(公开 ID,用于 GraphQL 查询)
• site_token(私密 token,用于 beacon 上报)

我搞混了——把 site_tag 当成 token 注入到 head 里,beacon 上报全部被 CF 丢弃。 等了 1.5 小时以为是”数据收集需要时间”,用 GraphQL 跨 site 查账户总数据发现别的站正常、唯独 niuxue.org 0 条,才反应过来。

修复:用真正的 site_token。CF 文档没说清这两个 ID 的区别,是个普遍踩坑警示。

❌ 坑 2:AI edit 返回 RGB 模式 PNG(没 alpha 通道)

给 logo 加「牛学」中文字时,AI 把透明背景画成了灰白 checker pattern——浏览器上看就是个丑陋的格子。

修复:用 PIL 重写 alpha 通道,把 checker pattern 变回 transparent。

❌ 坑 3:Starlight 严格 schema

加 frontmatter pubDate: 2026-05-16 直接 build 失败:YAML 把它解析成 Date 对象,但 Starlight schema 要 string。

修复:改 Starlight schema 用 z.coerce.date() 转换。

❌ 坑 4:明暗模式只翻一半

自己挖的坑——重新定义了 Starlight 灰色变量,但忘了在 light 模式 override,导致切换无效。

修复:在 light 跟 dark 两套 CSS variable 里都定义一遍。

❌ 坑 5:OG image 全站同一张

朋友圈分享时,19 篇文章卡片都长一样——读者根本分不清哪一篇。

修复:用 PIL + Noto CJK 字体 + 模板,批量生成 per-article OG 图。每篇文章 1200x630 自己的卡片。

❌ 坑 6:Reply form 默认显示「正在回复 」空白

Astro 渲染 hidden 属性在某些情况下没生效,导致评论区显示一个空白的”正在回复 “提示框。

修复:加 CSS [hidden] { display: none !important } 兜底。

❌ 坑 7:dist 路径搞错

wrangler pages deploy ./dist 跑成功但加了功能没生效——原因是 pages_build_output_dir 没配。

修复:改 wrangler.toml 加上配置就对。

每个坑都浪费过 20-60 分钟。把它们写下来给后来人省时间——这就是 niuxue.org 想做的事。

设计迭代:折腾最久的部分

设计是 niuxue.org 折腾最久的地方,连续改了 4-5 轮:

轮次	改了什么
1	Hero 装饰:默认 Starlight 模板 → photo-illustration(人在夜里用电脑)→ 但「不融合」→ 改成抽象能量图 → 最后变成 logo 化处理(牛角 + 圆球 + 「牛学」字)
2	顶部品牌名:纯英文「niuxue.org」 → 加中文「牛学 · niuxue.org」(中点分隔,中英对应)
3	配色:用 Hono 文档主色 #ff6432 暖橙做 accent,dark 模式做默认
4	字体:Inter(英文) + Noto Sans CJK SC(中文) + JetBrains Mono(代码)
5	明暗切换:自己挖的坑(见坑 4),修了

每一步迭代都丢给 Claude Code 改 CSS + 部署 + 截图比对,平均一次循环 5 分钟。

这套站能教你 3 件事

💡 1. 选 stack 不靠”什么最潮”,靠”满足约束最少”

我们没用 React / Next.js / Vercel —— 不是它们不好,是对我们的约束(免费 + 国内可达)不够紧。

Astro Starlight + Cloudflare Pages —— 两套加起来正好满足全部 3 条灵魂约束,多一个组件都是负担。

选型秘诀:先列约束,再列候选,选最少候选满足全部约束的。

💡 2. 一个账号 + 全栈,比”最好的服务拼起来”快 10 倍

我们没用 Auth0 做认证 / Supabase 做数据库 / Mixpanel 做分析 —— 每个都比 CF 对应服务”更好一些”,但要管 5 个账号 / 5 套 secret / 5 个 dashboard。

Cloudflare 一个账号 —— 服务略弱但集成无摩擦,3 倍生产力。

整合 > 最优,特别是个人项目。

💡 3. AI 写代码,你写决策

整个 8 小时,我没手写过一行代码 —— 全是 Claude 写。

我做的事:

• 挑技术栈(读 Claude 的方案对比 → 拍板)
• 判断设计(看 Claude 生成的 hero → 觉得不行 → 提反馈)
• 决定踩坑修法(Claude 给 3 个方案 → 选最稳的)
• 审稿(看文章风格对不对 → 改)

AI 不替代你思考,替代你做”已知怎么做但费时间”的事。这是 2026 年普通人创业的真实剧本。

接下来想做什么

短期:

• 补齐 03 区 / 04 区(VS Code / 桌面 App / Web 版 / Hooks / MCP / Routines / Channels…)
• 把 02 区 + 05 区里有遗漏的细节补上
• 加 RSS 订阅(让读者能 follow)

中期:

• 加搜索高亮 / 索引优化
• 启用文章评论邮件通知(你回我留言,作者收邮件提醒)

长期:

• 多语言(英文版?要不要做?看流量)
• 衍生产品 —— 把这套 stack 模版化,让其他人也能 5 小时搭一个免费教程站

顺便:这个站的源码后面会开源(Apache 2.0)。反 paywall 是 niuxue.org 的灵魂,开源是它的底色。到时候 fork 一份改改就能用。

05 区完结撒花 🎉🎉🎉

恭喜你看完了「真实案例」全部 5 篇。

• ✅ AI 是配人格的伙伴 → 一窝 Claude bot
• ✅ 30 字需求 3 天能上线网页 app → 自建 Web Chat 三天上线
• ✅ 一周做一个小工具是新常态 → 工时表 + E-ink Dashboard
• ✅ 痛点 + 目标用户 + 反直觉设计 → MoldPage:把”找工作的痛”做成产品
• ✅ 105 元一年搭一个全功能教程站 → 你正在看的这一篇

这 5 篇的核心信息:AI 工具不会替你思考,但会替你做”已知怎么做但费时间”的事。

剩下的——只看你愿不愿意动手。

下一步:03 区跟 04 区即将开放

接下来 niuxue.org 还会陆续上线:

• 03 区:给我的项目用 —— VS Code 插件、桌面 App、Hooks、MCP、Subagents、Worktrees(进阶 / 程序员玩法)
• 04 区:进阶玩法 —— Routines、Remote Control、Channels、Agent Teams、Auto Mode(老手专属)

想第一时间收到,可以收藏 niuxue.org 主页。

---

如果你也想搭一个 jamstack 教程站,按这一篇做就行。全过程不需要懂代码 —— Claude Code 帮你写,你只管说话。源码开源后会贴在这里。

踩过类似的坑、做过类似的站?发邮箱 [email protected],精选案例会进「普通人 + AI 落地」社区合集。