AstroPaper 模板速查手册

这个博客基于 AstroPaper v6，静态构建后部署在 Cloudflare Workers 上。下面按「配置 → 写作 → 功能 → 部署 → 排错」整理，方便随时回来查。

目录

技术栈

常用命令

目录结构

.
├── astro-paper.config.ts      # 站点配置（标题、域名、功能开关、社交链接…）
├── astro.config.ts            # Astro 配置（i18n、Markdown 插件、Shiki、字体）
├── wrangler.jsonc             # Cloudflare Workers 静态资源配置
├── cf/_headers                # 响应头（构建时复制到 dist）
├── scripts/cf-headers.mjs     # 把 cf/_headers 注入 dist
├── public/                    # 原样发布的静态文件（favicon、默认 OG 图）
└── src/
    ├── assets/
    │   ├── icons/             # 图标（含 socials/*.svg）
    │   └── images/            # 文章图片（走 Astro 图片管线）
    ├── components/            # Header、Footer、Card、分页、面包屑…
    ├── content/
    │   ├── pages/about.md     # 「关于」页
    │   └── posts/             # 文章
    ├── i18n/
    │   ├── index.ts           # useTranslations / tplStr
    │   ├── types.ts           # UIStrings 接口
    │   └── lang/{en,zh-CN}.ts # 界面文案
    ├── layouts/               # Layout（全站）、PostLayout（文章 SEO）
    ├── pages/                 # 路由
    ├── styles/                # global / theme / typography
    ├── types/config.ts        # 配置类型定义
    └── utils/                 # 排序、过滤、slug、OG 路径等

站点配置

全部在 astro-paper.config.ts 里，类型定义在 src/types/config.ts。

站点信息 site

首页 home

文章与分页 posts

功能开关 features

社交与分享 socials / shareLinks

name 必须对应 src/assets/icons/socials/ 下的 SVG 文件名。现成可用的有：github、x、linkedin、mail、facebook、pinterest、telegram、whatsapp。

socials: [{ name: "github", url: "https://github.com/you" }],
shareLinks: [{ name: "x", url: "https://x.com/intent/post?url=" }],

linkTitle 可以覆盖 aria-label，不填会自动生成。

写文章

文件位置与 URL

文章放在 src/content/posts/，支持 .md 和 .mdx。

另外可以在 frontmatter 里用 slug 覆盖文件名带来的路径段，例如 slug: hello-world。改动 slug 或文件名会改变 URL，旧链接会 404，没有自动重定向。

Frontmatter

只有 title、description、pubDatetime 是必填的。

---
title: "文章标题"
pubDatetime: 2026-10-20T20:00:00+08:00
description: "一句话摘要。"
tags:
  - 随笔
draft: false
---

草稿与定时发布

• draft: true：任何环境都不构建。
• pubDatetime 在未来：生产构建不会生成页面（包括 OG 图），本地 dev 下可见。
• 判断逻辑在 src/utils/postFilter.ts，提前量由 posts.scheduledPostMargin 控制。

图片

MDX 里可以 import 图片拿元数据，本项目的大小端示意图就是这么用的：

import diagram from "@/assets/images/endianness.svg";

<img
  src={diagram.src}
  width={diagram.width}
  height={diagram.height}
  alt="示意图"
/>

目录（TOC）

在文章里写一个二级标题 ## 目录（或 ## Table of contents），remark-toc 会把后面的标题自动生成目录列表，remark-collapse 把它折叠成「展开目录」。

• 正文标题用 h2～h6，h1 留给 frontmatter 的 title。
• 目录是构建时生成的，增删小节不需要手动维护。

代码块

```ts file="src/utils/foo.ts"
export const answer = 42;
```

• file="..." 会在代码块左上角显示文件名徽标（transformerFileName）。
• 行内标注（Shiki transformers）：

代码主题是 min-light / night-owl，跟随明暗模式切换；wrap: false，超长代码横向滚动。

Callouts（提示块）

基于 rehype-callouts，用引用块语法：

> [!NOTE]
> 补充说明。

> [!WARNING]- 默认折叠的警告
> 点开才显示。

> [!TIP]+ 默认展开但可折叠
> 一开始是展开的。

支持的类型：NOTE、ABSTRACT、INFO、TODO、TIP、SUCCESS、QUESTION、WARNING、FAILURE、DANGER、BUG、EXAMPLE、QUOTE。

类型后面直接写文字可以自定义标题；加 - 默认折叠，加 + 默认展开。

表格

普通 Markdown 表格即可。内容较宽时，可以在 MDX 里套一层响应式容器：

import ResponsiveTable from "@/components/ResponsiveTable.astro";

<ResponsiveTable variant="striped-minimal">
  | 列 1 | 列 2 | | ---- | ---- | | 内容 | 内容 |
</ResponsiveTable>

variant 可选 minimal（无边框）、striped（斑马纹）、striped-minimal（斑马纹 + 无边框）。

数学公式（默认未启用）

需要自己加插件：

pnpm add remark-math rehype-katex katex

然后在 astro.config.ts 的 remarkPlugins 里加 remarkMath，rehypePlugins 里加 rehypeKatex，并在 Layout.astro 里引入 katex/dist/katex.min.css（或在页面里用 CDN 链接）。

页面与路由

主题与样式

颜色

src/styles/theme.css 定义设计令牌，并通过 Tailwind 的 @theme 暴露成工具类：

改配色只需要改 :root 和 [data-theme="dark"] 两组值。

字体

字体在 astro.config.ts 的 fonts 数组里声明（Astro Fonts API，构建时下载并自托管），当前用的是 Google Sans Code，并映射为 --font-app：

--font-app: var(--font-google-sans-code);

换字体：在 fonts 数组里加一项（name、cssVariable、provider、weights…），再把 theme.css 里的 --font-app 指向新的变量。

明暗模式与过渡

• 切换按钮在 Header.astro，主题存在 localStorage 的 theme 键里，跟随系统偏好，首屏有内联脚本避免闪烁。
• 全站启用了 Astro 的 ClientRouter（View Transitions），页面切换有淡入效果。

排版

文章容器用 .app-prose（@tailwindcss/typography 的 prose 加主题覆盖），相关样式在 src/styles/typography.css。

多语言（i18n）

• 界面文案在 src/i18n/lang/*.ts，实现 UIStrings 接口；缺失的 key 会回退到 en.ts。
• 语言由 site.lang 和 astro.config.ts 的 i18n.locales 共同决定，两者必须一致，否则 getRelativeLocaleUrl 会抛 MissingLocaleError。
• 新增语言：加 src/i18n/lang/xx.ts → 把 xx 加进 i18n.locales → 改 site.lang。
• 日期格式在 Datetime.astro 里按语言前缀处理：zh 用 YYYY年M月D日，其余用 D MMM, YYYY。

SEO 与订阅

• 每页都有 canonical、description、Open Graph / Twitter Card 元数据。
• 文章页输出 BlogPosting 结构化数据（标题、作者、发布时间、修改时间、图片）。
• 动态 OG：satori 渲染 SVG，sharp 转 PNG，字体通过 astro:assets 获取；文章没有自定义 ogImage 时自动生成。
• sitemap 由 @astrojs/sitemap 生成，showArchives 关闭时会自动过滤归档页。
• RSS 在 /rss.xml，Layout.astro 里有 <link rel="alternate"> 自动发现。
• Google 站点验证：site.googleVerification，或构建时提供 PUBLIC_GOOGLE_SITE_VERIFICATION 环境变量。

搜索

• 用 Pagefind：构建时扫描 dist，只索引带 data-pagefind-body 的页面（文章正文）。
• 搜索页 /search/ 用 @pagefind/default-ui 渲染，支持中文分词，无需任何后端。
• 索引产物在 dist/pagefind/，构建后还会复制一份到 public/pagefind/（已 gitignore）。
• features.search: false 会隐藏导航里的搜索入口，并把 /search/ 重写为 404。

部署到 Cloudflare

纯静态站点，不需要任何 adapter。配置在 wrangler.jsonc：

{
  "name": "lab-blog",
  "compatibility_date": "2026-10-20",
  "assets": {
    "directory": "./dist",
    "not_found_handling": "404-page",
  },
}

方式一：连接 Git 自动部署（推荐）

1. Cloudflare Dashboard → Workers & Pages → Create application → Workers → Import a repository
2. Build command：pnpm build
3. Deploy command：npx wrangler deploy
4. 环境变量：NODE_VERSION=24（Astro 7 要求 Node ≥ 22.12）
5. 之后每次 push 到 main 自动构建，PR 会有预览部署

方式二：本地命令行

npx wrangler login
pnpm deploy

域名

Worker → Settings → Domains & Routes → Add custom domain。绑定后把 astro-paper.config.ts 的 site.url 改成新域名，再部署一次，否则 canonical / sitemap / RSS 还是旧地址。

响应头

cf/_headers 在构建时复制到 dist/_headers：/_astro/* 长缓存，其余加 X-Content-Type-Options、Referrer-Policy、X-Frame-Options。

配额

Workers 免费版静态资源上限约 25 MiB，目前构建产物约 8～9 MB，文章图片多了要留意体积。

排错清单

快速索引