环境要求
- Node.js 18.17.1+（建议 20 LTS / 22）
- 任意包管理器（npm / pnpm / yarn，下文以 npm 为例）
安装与启动
cd geek-weekly
npm install # 首次安装依赖
npm run dev # 本地预览，访问 http://localhost:4321修改任意 Markdown 或样式后，dev 服务器会自动刷新，无需重启。
构建与预览产物
npm run build # 构建成纯静态文件，输出到 dist/
npm run preview # 以生产模式预览 dist/ 内容新增一期周报
在 src/content/issues/ 下新建 NNN.md，按模板填写。含 # 的标题必须加引号，否则 YAML 会把 # 后内容当注释。
---
title: "极客周报 #005" # ← 含 # 必须加引号
issue: 5
date: 2026-07-27
author: kookboy
tags: [AI, 开源, 自托管]
cover: /covers/005.svg
summary: 一句话摘要……
---
## 本周焦点
## AI & 大模型
## 开源瞭望
## 自托管实验室
## 效率工具箱
## 极客冷知识六大栏目用 ## 二级标题分隔，单期页会自动生成右侧目录锚点。保存后刷新浏览器，最新日期的一期会自动置顶为头条。
字段说明
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
title | 字符串 | 是 | 标题，含 # 必须加引号 |
issue | 数字 | 是 | 期号，仅用于展示 |
date | 日期 | 是 | 决定排序与「最新一期」 |
author | 字符串 | 否 | 默认 kookboy |
tags | 数组 | 否 | 归档页标签筛选依赖它 |
cover | 字符串 | 否 | 封面图路径 |
summary | 字符串 | 否 | 首页卡片 / RSS 摘要 |
编辑 / 删除一期
- 编辑：直接改对应
src/content/issues/NNN.md，刷新即生效。 - 删除：删除该
.md文件即可，首页、归档、RSS 会自动重算。
更换封面
把图片放进 public/covers/（支持 .svg / .png / .jpg），再在期号的 cover 字段填 /covers/你的图.svg。
修改站点信息
- 站名 / 导航 / 页脚：
src/layouts/Base.astro - 配色 / 字体：
src/styles/global.css顶部:root的 CSS 变量，改这里即可整体换肤 - RSS 标题与描述：
src/pages/rss.xml.ts
部署
- 修改
astro.config.mjs里的site为正式域名（RSS 链接依赖它）。 npm run build，把生成的dist/整体托管到 GitHub Pages / Cloudflare Pages / Nginx / 任意静态空间。- 订阅地址：
你的域名/rss.xml。
常见问题
标题只显示「极客周报」没有期号？
没加引号，#被 YAML 当注释了。改成"极客周报 #005"即可。
新增一期后首页没出现？
检查date是否晚于现有最新一期；排序按日期倒序，最新日期自动置顶。
本地端口被占用？
npm run dev -- --port 4322换一个端口。