项目结构

约 1489 字大约 5 分钟

2026-09-01

Shirone 是一个基于 Astro 7 + Svelte 5 + Tailwind CSS + TypeScript 构建的高性能现代化静态博客系统。项目遵循 关注点分离（SoC） 与 原子化设计规范（Atomic Design），具备清晰的模块边界与强类型配置约束。

本篇将通过文件树与代码树等多种展示形态，深入剖析 Shirone 的工程骨架与模块协作机制。

根目录架构总览

项目根目录包含了静态资源、构建配置、自动化脚本以及核心源码：

Shirone 工程根目录

public# 纯静态资源（favicon、自定义字体、robots.txt 等无需编译的文件）

src# 核心源码目录

scripts# 自动化构建与离线同步脚本

astro.config.mjs# Astro 顶层配置文件（集成 Svelte、Swup、Tailwind）

svelte.config.js# Svelte 5 编译器配置（启用 Runes 响应式）

tsconfig.json# TypeScript 路径映射与严格模式

package.json# 项目依赖与脚本命令

pnpm-lock.yaml# 锁版本清单

源码分层与模块职能 (`src/`)

src/ 目录根据功能域划分为七大核心模块：

src 源码分层解析

components# UI 组件库

config# 集中化强类型配置

content# 内容层

layouts# 骨架布局

pages# 文件系统路由

styles# 设计系统

utils# 业务工具库

核心配置驱动模型

Shirone 采用强类型配置驱动架构，所有的功能开关、个人信息与侧栏编排均收敛在 src/config/ 目录下：

核心配置驱动模块

src

config

siteConfig.ts

sidebarConfig.ts

musicConfig.ts

src/config/siteConfig.ts
import { withUserConfig } from "../utils/config-overlay";

export const siteConfig = withUserConfig("site", {
  title: "Shirone",
  subtitle: "Seeing the world from scratch",
  description: "基于 Astro 7 + Svelte 5 的现代化静态博客",
  author: "Matsuzaka Yuki",
  avatar: "/avatar.webp",
  favicon: "/favicon.svg",
  themeColor: "#6750a4", // Material 3 种子色
  enableSwup: true,       // 开启 SPA 无刷新平滑切页
  enablePagefind: true,   // 开启 WASM 本地全文字搜
});
src/config/sidebarConfig.ts
import { withUserConfig } from "../utils/config-overlay";

export const sidebarConfig = withUserConfig("sidebar", {
  position: "left", // "left" | "right" | "none"
  widgets: [
    { type: "profile", enable: true },
    { type: "announcement", enable: true },
    { type: "music", enable: true, sticky: true },
    { type: "tags", enable: true, maxCount: 20 },
    { type: "categories", enable: true },
  ],
});
src/config/musicConfig.ts
import { withUserConfig } from "../utils/config-overlay";

export const musicConfig = withUserConfig("music", {
  enable: true,
  provider: "mixed", // "local" | "meting" | "custom" | "mixed"
  meting: {
    server: "netease",
    type: "playlist",
    id: "14164869977",
  },
  defaultVolume: 0.7,
  defaultMode: "sequence",
});

文章内容体系与组织模式 (`src/content/posts/`)

文章内容支持两种组织策略，可在同一个仓库内自由混用：

文件夹方案 (推荐)

文件夹组织方案 (推荐)

2026-09-01-shirone-architecture

2026-09-02-webcrypto-guide

自包含资源：图片、多媒体与代码附件与文章存放在同一目录下，方便归档与迁移。
相对路径引用：在 Markdown 中直接使用 ./cover.webp 或 ./diagram.png 引用。

单文件方案 (极简)

单文件组织方案

2026-08-31-hello-world.md

2026-09-01-material-design-3.md

2026-09-02-typescript-tips.md

轻量扁平：无伴生本地多媒体资源时，直接以单个 .md 文件编写。
外链托管：适合图片统一托管在 CDN 或图床的场景。

构建输出与发布产物 (`dist/`)

执行 pnpm build 构建后，Astro 将生成完全解耦、零后端的纯静态 HTML 产物：

dist 静态构建产物

_astro# 打包编译后的 JS/CSS Chunk (含内容 Hash)

pagefind# Pagefind 静态全文索引 (WASM 运行时 + 倒排索引块)

posts# 预渲染文章静态 HTML 目录

rss.xml# RSS 2.0 订阅源

atom.xml# Atom 1.0 订阅源

sitemap-index.xml# SEO 站点地图索引

llms.txt# LLM 友好全站摘要

index.html# 站点首页

模块协作流程图

架构优势

极致首屏：文章内容与元数据完全由 Astro SSR 静态预渲染，核心阅读内容 0 客户端 JS。
渐进增强：交互组件（音乐、弹窗、设置面板）通过 Svelte 5 Runes 按需加载 (client:idle / client:visible)。
无缝切页：Swup 拦截站内链接点击，配合 Material 3 共享轴过渡动效实现 SPA 单页级丝滑体验。

版权所有

版权归属：matsuzaka-yuki

许可证：署名 4.0 国际 (CC-BY-4.0)

部署

markdown

组织

高级

代码块

图表

资源嵌入

用户

组件

项目结构

根目录架构总览

源码分层与模块职能 (`src/`)

核心配置驱动模型

文章内容体系与组织模式 (`src/content/posts/`)

构建输出与发布产物 (`dist/`)

模块协作流程图

版权所有

项目结构

根目录架构总览

源码分层与模块职能 (src/)

核心配置驱动模型

文章内容体系与组织模式 (src/content/posts/)

构建输出与发布产物 (dist/)

模块协作流程图

版权所有

源码分层与模块职能 (`src/`)

文章内容体系与组织模式 (`src/content/posts/`)

构建输出与发布产物 (`dist/`)