README 模板：从一句话简介到许可证
这是一份 README 骨架。下面整篇就是模板本身 —— 段落顺序、每段写多少、哪些可以省，都按实际项目里最常见的来。
拿来当范本用的项目叫 koka-site：一个四语作品集站点，Astro 静态生成，部署在 Cloudflare Pages。
简介
用一句话说清「这是什么、给谁用、解决什么问题」。不要超过两行。
一个四语（中 / 繁 / 日 / 英）的作品集站点。Astro 静态生成，零后端，部署到 Cloudflare Pages。
如果一句话说不清，说明项目定位还没想好 —— 这时候写 README 是在替自己想清楚。
特性
列 3–6 条，每条一行，用动词或名词短语开头，不要写完整句子。
- 四语路由，路径前缀与语言一一对应
- 注册表驱动：加一个板块只改一处配置
- 明暗双主题，未设属性时跟随系统
- 零后端，纯静态产物，可直接丢 CDN
- 自托管字体，无第三方请求
技术栈
| 层 | 选型 | 为什么 |
|---|---|---|
| 框架 | Astro | 默认零 JS，需要交互时才挂脚本 |
| 内容 | Content Collections | 有 schema 校验，写错字段会构建失败 |
| 样式 | 原生 CSS + 令牌 | 站点规模不大，不值得引框架 |
| 部署 | Cloudflare Pages | 静态产物，免费额度够用 |
快速开始
环境要求
Node.js >= 22
npm >= 10安装
git clone git@github.com:kokacamera/astro.git
cd astro
npm install开发
npm run dev
# → http://localhost:4321构建与预览
npm run build # 产物在 dist/
npm run preview # 本地预览构建结果配置
站点的主要配置集中在 src/site.config.ts —— 它是唯一真源，导航、路由、页脚都从这里派生。
export const SECTIONS = [
{ id: 'blog', kind: 'collection', order: 1 },
{ id: 'about', kind: 'page', order: 5 },
// 加板块 = 加一条
];
export const PAGE_SIZE = 5; // 列表每页条数
export const CONTACT_EMAIL = '...'; // 联系页的 mailto常用命令：
| 命令 | 作用 |
|---|---|
npm run dev |
本地开发，热更新 |
npm run build |
构建到 dist/ |
npm run preview |
预览构建产物 |
npm run format |
Prettier 格式化全仓 |
npm run format:check |
校验格式（CI 用） |
目录结构
src/
├── site.config.ts # 注册表：语言 + 板块（唯一真源）
├── i18n/ # 文案表 + t(lang, key)
├── styles/
│ ├── tokens.css # 设计令牌（明暗两套值，变量名不变）
│ └── base.css # 重置 + 基础元素 + 工具类
├── content/<集合>/<lang>/<slug>.md
├── lib/content.ts # 按语言取条目、格式化日期
├── layouts/BaseLayout.astro
├── components/ # Header / Footer / PostList / Pagination …
└── pages/[lang]/... # 所有页面按语言前缀生成部署
推送到 main 后由 Cloudflare Pages 自动构建。手动部署：
npm run build
npx wrangler pages deploy dist --project-name=<项目名>环境变量在 Cloudflare 控制台配置，不要写进仓库：
| 变量 | 说明 |
|---|---|
CLOUDFLARE_API_TOKEN |
部署用，仅 CI 需要 |
CONTACT_EMAIL |
联系页收件地址 |
常见问题
Q：构建失败提示 z.coerce.date() 解析错误？
A：pubDate 写成了非日期格式。写成 2026-10-07 或带引号的 ISO 字符串都可以，但必须是可解析的日期。
Q：新加的板块没出现在导航里？
A：检查 SECTIONS 里那条有没有 enabled: false。默认是启用的。
贡献
- Fork 本仓库，从
main切一个分支。 - 一次提交只做一件事，提交信息写清「改了什么、为什么」。
- 提交前跑一遍
npm run format:check。 - 提 PR，说明改动范围和验证方式。
许可证
MIT © koka
写 README 时最常犯的三个错
- 简介写成了宣传语。 「让世界更美好」不是简介，「一个四语静态作品集站」才是。
- 安装步骤默认读者什么都知道。 写全
cd和npm install，别省。 - 把「以后会做」写进特性。 特性列的是现在有的东西。计划中的放 Issues，别放 README。
一份 README 合格的标准很简单：一个没用过这个项目的人，照着它能不能跑起来。能，就够了。