英文原文正文为项目原始 README（英文），本站后续会翻译为中文，当前仅剔除图片与无关章节并统一排版。

星际仙人掌

Astro Cactus 是一个基于 Astro 构建的简单且有特定用法偏好的入门项目。使用它可以创建一个易于使用的博客或网站。

主要功能

• Astro v7 快速 🚀
• Tailwind v4
• 可访问的、语义化的 HTML 标记
• 响应式 & SEO 友好
• 暗黑 & 亮色模式
• MD & MDX 文章 & 笔记
  • 包含 提示
• Satori 用于创建 Open Graph PNG 图片
• 自动 RSS 订阅
• 网络提及
• 自动生成：
  • sitemap
  • robots.txt
  • Web 应用程序清单
• Pagefind 静态搜索库集成
• Astro Icon SVG 图标组件
• Expressive Code 代码块和语法高亮

演示 💻

查看托管在 Netlify 上的 演示

快速开始

从此模板创建一个新的仓库。

# npm 7+
npm create astro@latest -- --template chrismwilliams/astro-theme-cactus

# pnpm
pnpm dlx create-astro --template chrismwilliams/astro-theme-cactus

预览

命令

将 pnpm 替换为你选择的 npm / yarn

配置

• 编辑模板的配置文件 src/site.config.ts
  • 重要：将 url 属性设置为你自己的域名。
  • 修改由 Expressive Code 生成的 markdown 代码块的设置。Astro Cactus 提供暗色主题（dracula）和浅色主题（github-light）。你可以在 @ expressive-code 找到更多选项。
• 更新文件 astro.config.ts
  • astro-webmanifest 选项
• 替换并更新 /public 文件夹中的文件：
  • icon.svg - 用作创建网站图标（favicon）和 manifest 图标的源文件
  • social-card.png - 用作默认 og:image
• 用你自己的浅色和深色样式修改文件 src/styles/global.css，并自定义 Tailwind 的主题设置。
• 编辑 src/components/SocialList.astro 中的社交链接以添加/替换你的媒体资料。图标可在 icones.js.org 找到，根据 Astro Icon 的说明 使用。
• 在 src/content/post/ 和 src/content/note/ 中为你的博客创建/编辑文章和笔记，文件格式为 .md 或 .mdx。更多详情见 下文。
  • 阅读 这篇文章 了解如何向你的网站添加 webmentions。
  • 为相关博客文章在 /src/content/tag/ 中添加自定义标签页面，确保文件名与标签名相同。
• OG 图片：
  • 如果你想更改 Satori 库生成的图片样式，请打开 src/pages/og-image/_ogMarkup.ts 中的 markup 函数，在其中根据需要编辑 html/tailwind 类。你可以使用这个 在线工具 设计你的图片。
  • 你也可以创建自己的 og 图片，并通过在 frontmatter 中添加 ogImage 属性且指向资产链接，跳过 Satori 的生成。一个示例可见于 src/content/post/testing/social-image.md。关于 frontmatter 的更多信息见 下文。
• 可选：
  • 字体：该主题在 src/layouts/Base.astro 中的 <body> 元素上设置了 font-mono 作为字体族。你可以通过移除 font-mono 变体来更改字体，此后 TailwindCSS 将默认使用 font-sans 字体族栈。

更新

如果你已经分叉了这个模板，你可以将分叉同步到你自己的项目中，记住不要点击丢弃更改，否则你会丢失你自己的改动。

如果你有一个模板仓库，你可以将这个模板作为远程仓库添加，如这里讨论的。

添加帖子、笔记和标签

此主题使用 内容集合 来组织本地 Markdown 和 MDX 文件，并通过 schema 对 frontmatter 进行类型检查 -> src/content.config.ts。

添加文章/笔记/标签 就像将你的 .md(x) 文件添加到 src/content/post、src/content/note 或 src/content/tag 文件夹一样简单，文件名将用作 slug/url。

Tag 集合允许你覆盖生成的标签页面的内容。例如，模板包含 src/content/tag/test.md，它会覆盖在 your-domain.com/tags/test 显示的内容。

注意
要使标签页面正常工作，文件名 (src/content/tag/*) 必须也出现在文章的 tags frontmatter.

此模板中包含的文章/笔记/标签作为示例，用于展示如何结构化你的 frontmatter。此外，Astro 文档 对 markdown 页面有详细说明。

文章前言

注意前言部分

标签前件

Frontmatter 代码片段

Astro Cactus 包含一个有用的 VSCode 代码片段，它可为帖子和笔记创建 frontmatter“模板”，位置在 -> .vscode/post.code-snippets。在新创建的 .md(x) 文件中开始输入单词 frontmatter 即可触发。通过 Visual Studio Code 的 IntelliSense（mac 上为 ⌃Space，Windows 上为 Ctrl Space）可以显示代码片段。

Pagefind 搜索

此集成提供了一个用于搜索博客帖子和笔记的静态搜索功能。在目前的形态下，pagefind 只在站点构建完成后生效。该主题添加了一个 postbuild 脚本，应在 Astro 构建站点后运行。你可以通过同时运行 build && postbuild 在本地预览。

搜索结果仅包括来自帖子和笔记的页面。如果你想包含其他/所有页面，请移除或重新定位 data-pagefind-body 属性至 src/layouts/BlogPost.astro 和 src/components/note/Note.astro 中的 article 标签。

它还允许你根据博客帖子 frontmatter 中添加的标签来筛选帖子。如果你不想使用此功能，请移除 src/components/blog/Masthead.astro 中链接的 data-pagefind-filter="tag" 数据属性。

如果你不想包含此集成，只需移除组件 src/components/Search.astro，并从 package.json 中卸载 @pagefind/default-ui 和 pagefind。你还需要从此处移除 postbuild 脚本。

你可以减少 CSS 的初始加载量，如这里所示，通过延迟加载 web 组件样式。

分析

您可能希望跟踪访问您博客/网站的访客数量，以便了解趋势以及您创建的热门帖子/页面。有许多可供使用的提供商，包括网页托管服务商，如 vercel、netlify 和 cloudflare。

此主题/模板没有包含特定的解决方案，因为存在多种用例和/或选项，有些人可能会使用，有些人可能不会。

在设置网站时，您可能会被要求将一小段代码添加到网站的 HEAD 标签中，该代码可以在 src/layouts/Base.astro 中找到。或者，您也可以将这段代码添加到 src/components/BaseHead.astro 中。

部署

有关指导，Astro 文档 对如何在各种平台上部署你自己的 Astro 站点及其特性进行了详细说明。

默认情况下，主题会对所有页面和端点进行预渲染，并使用 'static' 输出 以及 './dist' 输出目录。

使用此主题不需要添加任何适配器。

Cloudflare 工作者

如果通过 Cloudflare Workers 部署，您可能会在 OG 图像端点以及需要 Node 环境方面遇到问题。为了解决这个问题，您需要为静态构建添加一个Wrangler 配置文件。

{
  "name": "astro-cactus",
  // Set this to today's date
  "compatibility_date": "2026-05-11",
  "assets": {
    "directory": "./dist",
    "not_found_handling": "404-page"
  }
}

如果您打算使用 Clouflare 适配器，请将 prerenderEnvironment 设置为 'node'，并遵循 Cloudflare 文档。

请注意 nodejs_compat 标志，以及在撰写本文时 Cloudflare 文档中的主要入口点不正确。

{
  "name": "astro-cactus",
  "main": "@astrojs/cloudflare/entrypoints/server",
  // Set this to today's date
  "compatibility_date": "2026-05-11",
  "compatibility_flags": ["global_fetch_strictly_public", "nodejs_compat"],
  "assets": {
    "binding": "ASSETS",
    "directory": "./dist",
    "not_found_handling": "404-page"
  },
  "observability": {
    "enabled": true
  }
}

子目录部署

这个主题默认不处理子目录/基本路径部署（例如 GitHub Pages 项目站点），并且会导致问题。

所有内部链接都是根绝对路径，并且不考虑 base 路径值。

如果你需要此功能，请参阅 Astro 关于base 和内部链接的文档。

致谢

这个主题的灵感来自 Hexo Theme Cactus

许可证

麻省理工学院