开发 1 · 先看这张地图:改哪里,不改哪里

你现在在哪,这章解决什么

你的站已经在赚钱,现在想动模板本身了——加个功能、换个结构、或者只是想知道「这个东西能不能改」。动手前先花 10 分钟搞清楚:任何一个改动,应该落在哪一层。改错位置,轻则白干,重则把站改坏、或下次升级模板时改动全被冲掉。

这章做完你会得到

一张「任何需求 30 秒定位到文件」的决策树
看懂一篇文章从草稿变成网页的完整流程

三层楼:谁住哪层,谁该动谁

层	住哪些目录	你会动它吗	升级模板时
内容层(一楼)	`src/content/wiki/`、各语言 JSON 里的首页数据	天天动(写文章)	几乎不冲突
配置层(二楼)	`src/config/`、`src/locales/`、`src/styles/globals.css`	换游戏时动一次	少量冲突,永远保留你的
代码层(三楼)	`src/pages/`、`src/components/`、`src/lib/`、`src/i18n/`	基本不动	模板作者给你新功能

三条楼层规矩:

改内容不碰框架,改配置不重写框架。
代码层里不允许出现你这个游戏专属的文字——所有界面文字都住在语言 JSON 里。
想改代码层之前,先问自己:这事真的不能靠配置解决吗?(多数时候能。)

改动决策树(贴在手边)

你要改什么?
├─ 界面上的文字/首页模块 → src/locales/<语言>.json(界面文字在根部,首页模块在 home.* 段)
├─ 游戏名/域名/作者信息  → src/config/site.ts
├─ 导航栏目              → 三处必须同时一致(见下)
├─ 主题色                → src/styles/globals.css 顶部 8 行(4 个变量 × 亮/暗两套)
├─ 语言列表              → 三处必须同时一致(见下)
├─ 文章内容              → src/content/wiki/<语言>/<栏目>/ 下的 .mdx
├─ 新组件/新页面         → 代码层,动了要考虑升级成本
└─ 广告/评论/统计开关    → Cloudflare 网页变量或 wrangler.toml(二选一,见「功能开关」章)

两条「三处一致」铁律(跑 pnpm check-config 自动检查):

栏目:配置里登记的栏目名 = 语言 JSON 里 nav.栏目名 = 内容目录 src/content/wiki/en/栏目名/,三处一模一样,少一处构建就报错。
语言:语言列表 = 语言 JSON 文件 = 内容目录,同样三处一致。

一篇文章是怎么变成网页的

先说结论:文章从草稿到上线,走四道工序。

1. 你(或 AI)写 .mdx 文章,开头是登记卡(frontmatter)
2. 质检员(Zod schema)检查登记卡,格式不对 → 构建直接失败,告诉你哪里错
3. 网站为每篇文章生成一个固定网址
4. 全部印成纯 HTML 文件,自动生成搜索索引

多语言有一条故意不对称的规矩:玩家打开一篇你只写了英文版的文章网址,网站会显示英文版(网址永不打不开);但栏目列表页只显示该语言真实存在的文章(不显示「骗人」的空页)。前者求「打得开」,后者求「不撒谎」。

Astro 5 的六个坑(只在改代码层时才需要读)

这六条全是实测踩出来的,改内容层/配置层用不到:

文章的内部编号自带 .mdx 后缀,但查询时要去掉后缀(仓库已封装,别自己拼字符串)。
旧版 Astro 的 entry.render() 写法已废除,用独立的 render() 函数。
getStaticPaths 函数是单独编译的,页面文件顶部的变量它看不见——数据要写进函数体内。
读取网址里的参数用 Astro.params.slug,不是 Astro.props.slug。
文章必须放在 src/content/wiki/<语言>/ 下,直接丢在 src/content/<语言>/ 会触发旧机制报错。
英文是默认语言,住在根路径(/),不要做 / 跳 /en/ 的重定向。

工程规矩速查(改代码层时遵守)

界面文字全部走语言 JSON,组件里不硬编码文字
主题色只动 4 个变量(--brand / --brand-light / --brand-h / --brand-s,文字安全色 --brand-text 由后两个自动算出,不用手改),组件里只许引用 var(--brand),禁止写死色号
分享卡片图、canonical 网址全用 https:// 开头的完整地址
域名只从 SITE_URL 变量读,必须带 https://
广告/评论变量空着 = 对应组件不渲染(保住开箱跑分满分)
界面不用 emoji,图标统一用 lucide

每次改完的三件套

pnpm check-config              # 三处一致性
pnpm typecheck                 # 类型检查,0 错误
pnpm build && pnpm check-links # 构建 + 全站死链检查

动了 src/lib/ 下的纯函数要加测试(pnpm test);动了文章内容加跑 pnpm check-content。

卡住了怎么办

「build 报错说栏目/语言不一致」:跑 pnpm check-config,它会指出哪三处对不上。
「我想改的样式不生效」:先确认你改的是变量层(4 个变量)而不是在组件里写死了色号;亮色和暗色两套都要改(共 8 行)。

✅ 验收(全部成立才算完成)

☐ 拿三个真实需求(如「改首页标题」「加一篇文章」「换个主色」)在决策树上各 30 秒内找到落点
☐ 说得出两条「三处一致」各管什么
☐ 本地三件套全绿

下一步

地图有了,去开发 2 · 加栏目与加语言:每个需求的分步操作和配套 AI 提示词;换皮肤改首页在开发 3。