方案简介

Twilight 是一个基于 Astro 框架构建、集成了 CMS 的静态博客模板。它面向想要搭建个人博客、作品集与展示页面的开发者与内容创作者，将内容管理、Markdown 增强、评论系统、数据分析与丰富的 UI/视觉效果整合为开箱即用的方案。项目支持部署到 Cloudflare、Netlify、Vercel、EdgeOne 等静态托管平台，并提供 Docker 与 docker-compose 配置，具备中/英/日三语界面与多语言页面翻译能力。

亮点与能力

• CMS 集成：带 OAuth 的 Headless CMS，便于内容管理
• 置顶与草稿：可置顶重要文章或在生产环境隐藏草稿
• 加密文章：AES 加密文章，通过密码访问
• 自动导航：自动生成文章导航、归档与目录
• Markdown 增强：GitHub 仓库卡片、音乐卡片、admonitions、代码块增强、Mermaid 图表、KaTeX 数学渲染
• 评论与分析：集成 Waline、Twikoo 评论系统与 Umami 访客分析
• 视觉效果：页面过渡动画、自定义主题色、动态壁纸、粒子特效、自定义字体
• 部署能力：支持 Cloudflare、Netlify、Vercel、EdgeOne 等静态托管平台，并提供 Docker 与 docker-compose 配置

组成与分工

• Astro：核心框架，负责静态站点构建与页面渲染
• Waline / Twikoo：评论系统，负责读者互动
• Umami：访客数据分析
• Mermaid：将 mermaid 代码块渲染为图表
• KaTeX：LaTeX 数学公式渲染
• pnpm：包管理器，用于安装依赖与运行脚本
• Docker：容器化部署支持

前置要求

• 需要 Git、Node.js 环境与 pnpm 包管理器
• 安装 pnpm 及项目依赖：

bash

Install pnpm if not already installed

npm install -g pnpm

Install project dependencies

pnpm install

实施步骤

1. Fork 仓库

点击右上角 Fork 按钮将仓库 fork 到你的 GitHub 账号。

2. 克隆仓库

点击 Code -> Open with GitHub Desktop，或运行：

bash
git clone

3. 安装依赖

在项目目录中运行：

bash
npm install -g pnpm
pnpm install

4. 配置博客

• 在 twilight.config.yaml 中自定义博客设置
• 在 src/content 中管理站点内容

5. 启动开发服务器

bash
pnpm dev

6. 构建与部署

使用 pnpm build 构建站点到 ./dist/，再部署到任意静态托管平台。

使用与配置要点

• 本地开发：pnpm dev
• 构建：pnpm build，产物在 ./dist/
• 本地预览构建结果：pnpm preview
• 运行 Astro 错误检查：pnpm check
• 创建新文章：pnpm new-post
• 运行 Astro CLI：pnpm astro ...

注意事项与常见问题

• 仓库中 pnpm lint 与 pnpm format（使用 Biome）命令已被弃用（划线标记）。
• 原型来自 Fuwari，灵感来自 Yukina 与 Mizuki，翻译使用了 gitee 的 translate 项目。

优缺点

• ✓ 功能丰富可深度定制
• ✓ 支持多平台静态托管
• ✕ 需 pnpm 环境配置

出处

本方案挖掘自开源项目 Spr-Aachen/Twilight，方案内容与实施命令均来自其 README 原文。