项目结构详细说明

完整目录树

takato-blog/
│
├── 📄 astro.config.ts          # ⚙️ Astro 核心配置文件
├── 📄 package.json              # 📦 项目依赖和脚本
├── 📄 tsconfig.json            # 🔷 TypeScript 配置
├── 📄 eslint.config.js         # ✅ ESLint 配置
├── 📄 .prettierrc.mjs          # 💅 Prettier 配置
│
├── 📁 public/                  # 🌐 静态资源（直接复制到构建输出）
│   ├── favicon.svg             # 网站图标
│   └── astropaper-og.jpg       # 默认 OG 图片
│
└── 📁 src/                     # 💻 源代码目录
    │
    ├── 📁 assets/              # 🎨 需要处理的资源文件
    │   ├── icons/              # SVG 图标组件
    │   │   ├── IconRss.svg
    │   │   ├── IconSearch.svg
    │   │   └── ...
    │   └── images/             # 图片资源
    │       └── AstroPaper-v3.png
    │
    ├── 📁 components/          # 🧩 Astro 组件（可复用 UI 组件）
    │   ├── BackButton.astro    # 返回按钮
    │   ├── BackToTopButton.astro # 回到顶部按钮
    │   ├── Breadcrumb.astro    # 面包屑导航
    │   ├── Card.astro          # 文章卡片组件
    │   ├── Datetime.astro      # 日期时间显示
    │   ├── EditPost.astro      # 编辑文章链接
    │   ├── Footer.astro        # 页脚组件
    │   ├── Header.astro        # 页头组件
    │   ├── LinkButton.astro    # 链接按钮
    │   ├── Pagination.astro    # 分页组件
    │   ├── ShareLinks.astro    # 分享链接
    │   ├── Socials.astro       # 社交媒体链接
    │   └── Tag.astro           # 标签组件
    │
    ├── 📁 layouts/             # 🎨 布局组件（页面框架）
    │   ├── Layout.astro        # 基础布局（HTML 结构、SEO）
    │   ├── Main.astro          # 主布局包装器
    │   ├── PostDetails.astro   # 文章详情页布局
    │   └── AboutLayout.astro   # 关于页布局
    │
    ├── 📁 pages/               # 🛣️ 路由页面（文件系统路由）
    │   ├── index.astro         # 首页 (/)
    │   ├── 404.astro           # 404 错误页
    │   ├── about.md            # 关于页 (/about)
    │   ├── search.astro        # 搜索页 (/search)
    │   │
    │   ├── 📁 archives/        # 归档页
    │   │   └── index.astro     # /archives
    │   │
    │   ├── 📁 posts/           # 文章相关路由
    │   │   ├── [...page].astro # 文章列表页 (/posts, /posts/2, ...)
    │   │   └── [...slug]/      # 动态文章详情页
    │   │       ├── index.astro # /posts/文章-slug
    │   │       └── index.png.ts # 动态生成 OG 图片
    │   │
    │   ├── 📁 tags/            # 标签相关路由
    │   │   ├── index.astro     # 标签列表页 (/tags)
    │   │   └── [tag]/          # 动态标签页
    │   │       └── [...page].astro # /tags/标签名, /tags/标签名/2
    │   │
    │   ├── og.png.ts           # 动态生成站点 OG 图片
    │   ├── robots.txt.ts       # 动态生成 robots.txt
    │   └── rss.xml.ts          # 动态生成 RSS 订阅
    │
    ├── 📁 data/                # 📝 内容数据（Markdown 文件）
    │   └── blog/               # 博客文章集合
    │       ├── adding-new-post.md
    │       ├── customizing-astropaper-theme-color-schemes.md
    │       ├── examples/       # 示例文章
    │       │   ├── example-draft-post.md
    │       │   ├── portfolio-website-development.md
    │       │   ├── tailwind-typography.md
    │       │   └── terminal-development.md
    │       └── _releases/     # 发布日志（以下划线开头，通常被忽略）
    │
    ├── 📁 styles/              # 🎨 全局样式
    │   ├── global.css          # 全局 CSS
    │   └── typography.css      # 排版样式
    │
    ├── 📁 utils/               # 🛠️ 工具函数
    │   ├── generateOgImages.ts # 生成 OG 图片
    │   ├── getPath.ts          # 生成路径
    │   ├── getPostsByGroupCondition.ts # 按条件分组文章
    │   ├── getPostsByTag.ts    # 按标签获取文章
    │   ├── getSortedPosts.ts   # 排序文章
    │   ├── getUniqueTags.ts    # 获取唯一标签
    │   ├── loadGoogleFont.ts   # 加载 Google 字体
    │   ├── postFilter.ts       # 文章过滤器
    │   ├── slugify.ts          # 生成 URL slug
    │   ├── og-templates/       # OG 图片模板
    │   │   ├── post.js
    │   │   └── site.js
    │   └── transformers/       # Markdown 转换器
    │       └── fileName.js
    │
    ├── 📁 scripts/             # 📜 客户端脚本
    │   └── theme.ts            # 主题切换脚本
    │
    ├── 📄 config.ts             # ⚙️ 站点配置
    ├── 📄 constants.ts          # 📋 常量定义
    ├── 📄 content.config.ts     # 📚 内容集合配置（定义 Markdown schema）
    └── 📄 env.d.ts              # 🔷 TypeScript 环境类型定义

各文件/目录详细说明

配置文件

`astro.config.ts`

作用： Astro 核心配置文件

配置站点 URL
配置集成插件（sitemap、RSS 等）
配置 Markdown 处理（代码高亮、插件）
配置 Vite（Tailwind CSS 等）
配置图片优化
配置环境变量

类比： Next.js 的 next.config.js

`package.json`

作用： 项目依赖和脚本

dev: 启动开发服务器
build: 构建生产版本
preview: 预览构建结果

`tsconfig.json`

作用： TypeScript 配置

路径别名：@/* → ./src/*
继承 Astro 的严格配置

静态资源

`public/`

作用： 静态文件目录

这些文件会直接复制到构建输出的根目录
不需要导入，直接通过路径访问
例如：/favicon.svg 对应 public/favicon.svg

类比： Next.js 的 public/ 目录

源代码目录 (`src/`)

`src/assets/`

作用： 需要处理的资源文件

图片、字体等会被 Astro 优化处理
需要导入使用：import icon from '@/assets/icons/IconRss.svg'
支持图片优化、格式转换等

与 public/ 的区别：

public/：直接复制，不处理
assets/：会被优化处理，需要导入

`src/components/`

作用： 可复用的 UI 组件

使用 .astro 扩展名
类似 React 组件或 Vue 组件
可以在页面和其他组件中使用

示例组件：

Card.astro: 文章卡片，显示标题、描述、日期
Header.astro: 网站头部，包含导航
Footer.astro: 网站底部
Tag.astro: 标签显示组件

`src/layouts/`

作用： 页面布局组件

提供页面的 HTML 结构框架
包含 SEO meta 标签、字体加载等
使用 <slot /> 插入页面内容

主要布局：

Layout.astro: 基础布局，包含 <html>, <head>, <body>
PostDetails.astro: 文章详情页专用布局
AboutLayout.astro: 关于页布局

类比： Next.js 的 _app.jsx 或 _document.jsx

`src/pages/`

作用： 文件系统路由

每个文件自动生成一个路由
index.astro → /
about.md → /about
posts/[...slug]/index.astro → /posts/文章-slug

路由规则：

index.astro → 目录根路径
[param].astro → 动态参数
[...slug].astro → 捕获所有路径
.md 文件也可以作为页面

特殊文件：

og.png.ts: 动态生成 OG 图片
robots.txt.ts: 动态生成 robots.txt
rss.xml.ts: 动态生成 RSS 订阅

类比： Next.js 的 pages/ 目录

`src/data/blog/`

作用： 博客文章内容（Markdown 文件）

使用 Markdown 格式编写文章
Frontmatter 定义文章元数据（标题、日期、标签等）
文件会被 content.config.ts 中的配置处理

文件命名：

普通文件：文章标题.md
以下划线开头：_releases/ 通常被忽略（用于草稿或特殊内容）

Markdown 结构：

---
title: 文章标题
pubDatetime: 2024-01-01T00:00:00Z
tags: [JavaScript, React]
draft: false
---

# 文章内容

`src/utils/`

作用： 工具函数

纯函数，可以在组件脚本中使用
处理文章数据、路径生成、过滤等

主要工具：

getSortedPosts.ts: 按日期排序文章
getPath.ts: 根据文章 ID 生成 URL 路径
slugify.ts: 将字符串转换为 URL 友好的 slug
postFilter.ts: 过滤文章（排除草稿等）

`src/styles/`

作用： 全局样式

global.css: 全局 CSS，包含 Tailwind 导入
typography.css: 排版相关样式

注意： 组件内的 <style> 标签默认是 scoped 的

`src/scripts/`

作用： 客户端脚本

theme.ts: 主题切换逻辑（深色/浅色模式）
这些脚本会在客户端运行

`src/config.ts`

作用： 站点配置

集中管理站点信息
网站 URL、作者、标题、描述等
分页设置、功能开关等

使用方式：

import { SITE } from "@/config";
// SITE.title, SITE.author, etc.

`src/content.config.ts`

作用： 内容集合配置

定义 Markdown 文件的 schema（数据结构）
使用 Zod 进行类型验证
定义哪些字段是必需的，哪些是可选的

示例：

const blog = defineCollection({
  loader: glob({ pattern: "**/*.md", base: "./src/data/blog" }),
  schema: z.object({
    title: z.string(), // 必需
    draft: z.boolean().optional(), // 可选
  }),
});

`src/constants.ts`

作用： 常量定义

定义社交媒体链接等常量
避免硬编码

数据流

文章从 Markdown 到页面的流程

1. Markdown 文件 (src/data/blog/*.md)
   ↓
2. content.config.ts 验证 schema
   ↓
3. getCollection("blog") 获取所有文章
   ↓
4. utils/getSortedPosts.ts 排序和过滤
   ↓
5. pages/index.astro 渲染到页面
   ↓
6. components/Card.astro 显示文章卡片

路由生成流程

1. pages/posts/[...slug]/index.astro
   ↓
2. getStaticPaths() 生成所有路径
   ↓
3. 构建时生成静态 HTML
   ↓
4. 访问 /posts/文章-slug 时返回对应页面

开发建议

添加新文章

在 src/data/blog/ 创建 .md 文件
填写 Frontmatter（标题、日期、标签等）
编写 Markdown 内容
构建时会自动出现在文章列表中

创建新页面

在 src/pages/ 创建 .astro 或 .md 文件
路由自动生成（文件名 = 路由路径）

创建新组件

在 src/components/ 创建 .astro 文件
在页面中导入使用：import MyComponent from '@/components/MyComponent.astro'

修改样式

全局样式：修改 src/styles/global.css
组件样式：在组件内的 <style> 标签中编写（默认 scoped）

项目结构详细说明

目录

完整目录树

各文件/目录详细说明

配置文件

astro.config.ts

package.json

tsconfig.json

静态资源

public/

源代码目录 (src/)

src/assets/

src/components/

src/layouts/

src/pages/

src/data/blog/

src/utils/

src/styles/

src/scripts/

src/config.ts

src/content.config.ts

src/constants.ts

数据流