Quick Start

快速开始与定制

两种上手方式，按需选择：

• 方案一：本地调试 —— 在自己电脑上跑起来，改文案、调样式、调试 API。
• 方案二：部署到 Cloudflare Pages —— 连接 Git 仓库直接上线，拿到 *.pages.dev 地址，之后 push 即自动部署。

环境要求

Node.js ≥ 22.12（本地调试与 Cloudflare 构建都需要）。

方案一：本地调试

1. 克隆并安装依赖

git clone https://github.com/<你的用户名>/<你的仓库>.git
cd <你的仓库>
npm install

只是想先看看效果，直接克隆模板仓库也行；正式建站建议先用 Use this template 生成自己的仓库（见方案二第 1 步）。

2. 只看页面：npm run dev

npm run dev        # http://localhost:4321

注意：npm run dev 只渲染页面，/api/* 由 Cloudflare Pages Functions 提供服务——本地留言墙会显示「加载失败」、投稿提交会报错，属正常现象。

3. 调试 API（留言墙 / 投稿）：wrangler pages dev

要本地调通 /api/*，先构建，再用 wrangler 起一个带 Functions 的本地服务：

npm run build
npx wrangler pages dev dist --d1 DB    # http://localhost:8788

• --d1 DB：本地模拟留言墙用的 D1 数据库（绑定名必须是 DB），数据落在 .wrangler/state/，与线上无关；表结构首次访问时自动创建。
• 投稿接口的 GITHUB_* 运行时变量：wrangler 会自动读取项目根目录的 .env（复制 .env.example 填好即可）；不配则投稿不可用，其余功能正常。
• 改动页面或内容后重新 npm run build，刷新页面即可看到最新效果。

方案二：部署到 Cloudflare Pages

1. 生成自己的仓库

在模板仓库页点 Use this template → Create a new repository（比 fork 干净，不带模板的提交历史）。

2. 连接仓库

Cloudflare Dashboard → Workers & Pages → Create → Pages → Connect to Git → 选择你的仓库。

3. 构建配置

配置项	值
Framework preset	None（或 Astro）
Build command	npm run build
Build output directory	dist
环境变量	NODE_VERSION = 22.12.0

保存后 Cloudflare 自动构建，完成即可访问 https://<项目名>.pages.dev。

4. 按需开启功能

初始部署后站点即可正常浏览，以下功能按需配置：

• 留言墙：创建 D1 数据库并绑定到 Pages（变量名 DB）→ Message-Board
• 在线投稿：创建 GitHub App 并配置 GITHUB_* 环境变量 → CMS-Bot

完整环境变量总表见 Deployment。之后每次 push 到默认分支（或合并投稿 PR）都会自动重新部署。

定制班级信息

1. src/site.config.ts：班级名、顶栏 logo、首屏徽章、首页统计数字——改这一个文件，全站所有「XX届X班」字样自动更新。
2. src/pages/index.astro：班级简介、人物志、荣誉、记忆墙的示例文案（搜索 20XX 和各区块的中文示例）。
3. public/js/index.js：首屏打字机轮播文案（lines 数组）。
4. 主题色（金色 #e6c068）在 public/css/*.css 中定义。

删除示例内容

模板自带三处示例，正式使用前删除前两个：

• src/content/20250101.md —— 示例文章
• src/songs/20250101-example.json —— 示例歌曲
• public/pages/static/cover-placeholder.svg —— 占位封面（可保留备用）

正式写内容请看 Content-Format。