# 发布 Astro 网站利用 Astro 的零运行时间 SSG 方法、部分水合和广泛的 Markdown 支持构建快速、内容驱动的静态网站。 ## 内容 * 快速启动 * 何时不使用 * 项目结构 * SSG、SSR、混合 * 内容集合 - 旧版、内容层 API、自定义加载器 * 语法高亮——Shiki、变形金刚、表达性代码 * 图表集成 — Mermaid、PlantUML、深色模式主题 * 客户端搜索 — Pagefind（控件、权重）、Fuse.js * 版本化文档 - Starlight，多版本 * 国际化——路由、后备 * 常见模式——分页、标签、RSS、表单 * 性能最佳实践 - 预取、关键 CSS * 部署 — Firebase URL 配置、GitHub 页面 * 预部署清单 * 测试和质量 - Vitest、Playwright、链接检查 * 故障排除 ## 快速入门 # 创建新项目（使用 Markdown 站点的博客模板） npm 创建 astro@latest # 开发 npm run dev # 本地服务器 http://localhost:4321 npm run build # 在 dist/ 中生成静态文件 npm run Preview # 预览生产版本 ## 何时不使用此技能重点关注**静态站点生成 (SSG)**。考虑其他方法： * **实时数据应用** \- 使用SSR模式与数据库连接 * **用户身份验证流程** \- 需要服务器端会话处理 * **具有动态库存的电子商务** \- 使用混合模式或完整 SSR * **单页应用程序（SPA）** \- 直接考虑 React/Vue 框架对于混合 SSG+SSR 模式，请参阅 Astro 的适配器文档。 ## 项目结构源代码/ 组件/ # Astro、React、Vue、Svelte 组件 content/ # 内容集合 (Markdown/MDX) config.ts # 集合模式 docs/ # 示例集合布局/ # 带槽的页面包装器 pages/ # 基于文件的路由 public/ # 静态资源（图像、字体、图标） astro.config.mjs # 框架配置 ## SSG、SSR、混合模式|页面渲染时 |使用案例 ---|---|--- **SSG**（默认）|构建时间|博客、文档、营销网站 **SSR** |每个请求 |动态数据、个性化 **混合** |两者的混合|静态页面+动态端点对于纯静态站点，使用默认的 `output: 'static'` \- 不需要适配器。 ## 内容收藏 ### 传统模式（Astro 4.x）在`src/content/config.ts`中定义模式：从“astro：content”导入{defineCollection，z}；导出常量集合 = { 文档：defineCollection({ 架构： z.object({ 标题: z.string(), 描述：z.string().可选(), 标签：z.array(z.string()).可选(), 顺序：z.number().可选()，草稿：z.boolean().default(false) }) }) }; ### 内容层 API (Astro 5.0+) 使用 `glob()` 加载器的新模式 - 大型站点的构建速度提高了 75%： // src/content.config.ts（注意：不同的文件名）从'astro：content'导入{defineCollection}；从 'astro/loaders' 导入 { glob }；从 'astro/zod' 导入 { z }； const 博客 = DefineCollection({ 加载器：glob({pattern:'**/*.md',base:'./src/data/blog'}), 模式：({ image }) => z.object({ 标题: z.string(), pubDate: z.coerce.date(), 草稿：z.boolean().default(false), cover: image(), // 验证图像存在 author:reference('authors'), // 跨集合引用 }) }); 导出常量集合 = { 博客 }; ### 高级架构模式模式：({ image }) => z.object({ cover: image(), // 验证 src/ 中的图像类别： z.enum(['科技', '新闻']), author:reference('authors'), // 跨集合引用相关帖子：z.array（参考（'博客'））.可选（）， }) ### 自定义加载器（远程内容）从外部 API（GitHub 版本、CMS 等）获取内容： // src/loaders/github-releases.ts 从 'astro/loaders' 导入类型 { Loader }；导出函数 githubReleasesLoader(repo: string): Loader { 返回{ name: 'github-releases', 加载：异步（{存储，记录器}）=> { logger.info(`正在获取 ${repo} 的版本`); const 响应 = 等待 fetch(`https://api.github.com/repos/${repo}/releases`); constreleases=awaitresponse.json(); for (const 版本的版本) { 商店.设置({ id：release.tag_name，数据：{ 版本：release.tag_name，发布地点：release.发布地点， body: release.body // Markdown 发行说明 } }); } } }; } 在 `content.config.ts` 中注册：从 './loaders/github-releases' 导入 { githubReleasesLoader }； constreleases=defineCollection({ 加载器：githubReleasesLoader('owner/repo'), 架构： z.object({ 版本：z.string(), 发布于：z.string(), 正文： z.string(), }) }); 查询和渲染集合： --- 从“astro：content”导入{getCollection}；导出异步函数 getStaticPaths() { const docs =等待 getCollection("docs"); 返回 docs.map(doc => ({ 参数：{ slug：doc.slug }，道具：{文档} })); } const { doc } = Astro.props; const { 内容 } = 等待 doc.render(); --- <文章>

{doc.data.title}

<内容/> ## 语法高亮 ### 基本 Shiki 配置从“astro/config”导入{defineConfig}；导出默认的defineConfig({ 降价：{ shiki配置：{ 主题：“github-dark”，换行：真 } } }); ### 双明/暗主题 shiki配置：{ 主题：{ 光：'github-light'，黑暗：'github-黑暗'， }, } 添加 CSS 来切换主题： @media（首选颜色方案：深色）{ .astro-code, .astro-code span { 颜色：var(--shiki-dark)！重要；背景颜色：var(--shiki-dark-bg)！重要； } } ### 线条突出显示和变压器 ```打字稿 {2,4} 常量 a = 1; 常量 b = 2; // 突出显示常量 c = 3; 控制台.log(a + b + c); // 突出显示 ```` **变形金刚四季 (Astro 4.14+):** 从'@shikijs/transformers'导入{transformerNotationFocus，transformerNotationDiff}； shiki配置：{ 变压器：[transformerNotationFocus()、transformerNotationDiff()]、 } 在代码中使用符号注释： * `// [!code focus]` \- 聚焦此行 * `// [!code ++]` \- 标记为加法（绿色） * `// [!code --]` \- 标记为删除（红色） ### 富有表现力的代码（推荐用于文档）丰富的代码块，带有复制按钮、文件名、差异突出显示： npm 安装 astro-expressive-code 从“astro-expressive-code”导入expressiveCode；导出默认的defineConfig({ 集成：[expressiveCode()]， }); 功能：复制按钮、文件选项卡、行标记、终端框架、文本标记。 ## 图集成 ### 美人鱼（推荐）安装 Astro 集成： npm install astro-mermaid 美人鱼 // astro.config.mjs 从'astro/config'导入{defineConfig}；从 'astro-mermaid' 导入美人鱼；导出默认的defineConfig({ 集成：[美人鱼（{主题：'默认'}）] }); 在 Markdown 中使用： ````美人鱼图 TD； A-->B； B-->C； ```` 特点：客户端渲染、自动主题切换、离线功能、无需剧作家。 **替代方案（构建时静态 SVG）：** 将 `rehype-mermaid` 与 Playwright 一起用于预渲染图表（需要 `npx playwright install --with-deps`）。 **深色模式主题策略：** 1. **CSS变量** \- 让浏览器在运行时解析颜色： // 美人鱼配置美人鱼.初始化({ 主题：“基地”，主题变量：{ PrimaryColor: 'var(--diagram-primary)', lineColor: 'var(--图表线)' } }); 2. **图片元素** \- 生成两个主题，与媒体查询交换： <图片> 流程图

3. **内联 SVG** \- 使用 CSS 定位 SVG 类（风险：样式冲突）： .dark .mermaid-svg .node 矩形 { 填充：var(--bg-dark); } ### PlantUML npx astro 添加 plantuml 在 Markdown 中使用： ````植物体 @startuml 爱丽丝 -> 鲍勃：你好鲍勃 --> 爱丽丝：嗨！ @enduml ```` ## 客户端搜索 ### Pagefind（推荐用于大型网站）在构建时建立索引的零配置静态搜索： npm 安装 pagefind 添加到 `package.json`: { “脚本”：{ "build": "astro build && npx pagefind --site dist", "postbuild": "pagefind --site dist" } } 在组件中的使用：

<脚本> window.addEventListener('DOMContentLoaded', () => { new PagefindUI({ element: '#search', showSubResults: true }); }); 特点：无外部服务，离线工作，自动索引，小捆绑（~10KB）。 **粒度索引控制：** <主要数据-pagefind-body>

页面标题

重要的介绍文字

<导航数据-pagefind-忽略> 相关帖子属性|目的 ---|--- `数据页查找正文` |仅限制对此元素的索引 `数据页查找忽略` |从索引中排除元素 `data-pagefind-meta="key"` |定义元数据字段 `data-pagefind-weight="10"` |提高相关性（默认值：1） ### Pagefind 与 Fuse.js 特色|寻页| Fuse.js ---|---|--- 建筑|预构建的二进制块 |运行时内存中带宽|低（仅加载所需的块）|高（下载完整索引）可扩展性| 10,000 多页 | < 500 页多语言 |原生词干 |手动配置使用案例|全球站点搜索|小列表过滤 ### Fuse.js（轻量级替代方案）对于具有自定义 UI 需求的小型网站： --- 从“astro：content”导入{getCollection}； const posts =等待 getCollection('博客'); const searchIndex = JSON.stringify(posts.map(post => ({ 标题：帖子.数据.标题， slug：post.slug，正文: post.body.slice(0, 500) }）））； ---

<脚本定义：vars={{ searchIndex }}> 从“fuse.js”导入保险丝； const 保险丝 = 新保险丝(JSON.parse(searchIndex), { 键：['标题'，'正文']，阈值：0.3 }); document.getElementById('搜索').addEventListener('输入', (e) => { const 结果 = fusion.search(e.target.value); const resultsEl = document.getElementById('结果'); // 安全地清除之前的结果结果El.replaceChildren(); // 使用安全 DOM 方法构建结果结果.forEach(r => { const li = document.createElement('li'); const link = document.createElement('a'); link.href = `/blog/${r.item.slug}`; link.textContent = r.item.title; li.appendChild(链接); 结果El.appendChild(li); }); }); 对于企业需求，请考虑 Algolia（托管搜索 API）。 ## 版本化文档 ### Starlight（推荐用于文档站点） Astro 上专门构建的文档框架： npm create astro@latest -- --template starlight 主要功能：内置搜索（Pagefind）、i18n、侧边栏导航、深色模式、组件覆盖。 // astro.config.mjs 从'astro/config'导入{defineConfig}；从“@astrojs/starlight”导入星光；导出默认的defineConfig({ 集成：[ 星光({ 标题：“我的文档”，侧边栏：[ { 标签：'指南'，自动生成：{ 目录：'指南' } }， { 标签：'参考'，自动生成：{ 目录：'参考' } }， ], }), ], }); ### 多版本文档模式使用基于文件夹的结构： src/内容/文档/ v1/ 入门.md api-参考.md v2/ 入门.md api-参考.md 新功能.md 对于 Starlight 版本控制，请使用“starlight-utils”插件： npm 安装 starlight-utils 从'astro/config'导入{defineConfig}；从“@astrojs/starlight”导入星光；从 'starlight-utils' 导入 starlightUtils；导出默认的defineConfig({ 集成：[ 星光({ 插件：[starlightUtils({ multiSidebar: { switcherStyle: 'dropdown' } })], 侧边栏：[ { 标签：'v2'，项目：[{ 标签：'指南'，自动生成：{ 目录：'v2' } }] }， { 标签：'v1'，项目：[{ 标签：'指南'，自动生成：{ 目录：'v1' } }] }， ], }), ], }); ## 国际化（i18n）在 `astro.config.mjs` 中配置：导出默认的defineConfig({ 国际化：{ 默认区域设置：“en”，区域设置：[“en”、“fr”、“es”]、路由：{ prefixDefaultLocale: false } } }); 按语言环境构建内容： src/内容/文档/ zh/ 入门.md 法国/ 入门.md 检测组件中的区域设置： --- const locale = Astro.currentLocale || '恩'; --- ### 缺失翻译的后备当翻译不存在时，显示带有横幅的英文内容： --- // src/pages/[lang]/[...slug].astro 从“astro：content”导入{ getCollection，getEntry }； const 语言 = ['en', 'es', 'fr']; const defaultLang = 'en'; 导出异步函数 getStaticPaths() { const englishDocs =等待 getCollection('docs', ({ id }) => id.startsWith('en/')); 常量路径= []； for (englishDocs 的 const doc) { const slug = doc.id.replace(/^en\//, ''); for (const lang of languages) { const localizedId = `${lang}/${slug}`; const localizedDoc =等待 getEntry('docs', localizedId); 路径.push({ 参数：{ lang, slug }, 道具：{ 条目：localizedDoc || doc, // 回退到英语 isFallback: !localizedDoc } }); } } 返回路径； } const { 条目, isFallback } = Astro.props; const { 内容 } = 等待条目.render(); --- {isFallback && (

此页面尚不支持您的语言。

)} <内容/> ## 常见模式 ### 分页列表对于拥有 50 多个帖子的网站，分为多个页面： --- // src/pages/blog/page/[page].astro 从“astro：content”导入{getCollection}；常量 POSTS_PER_PAGE = 10; 导出异步函数 getStaticPaths() { const allPosts =等待 getCollection("博客"); const TotalPages = Math.ceil(allPosts.length / POSTS_PER_PAGE); return Array.from({ 长度: 总页数 }, (_, i) => ({ 参数：{ 页：字符串(i + 1) }, })); } const { 页 } = Astro.params; const pageNum = parseInt(页); const allPosts =等待 getCollection("博客"); const SortedPosts = allPosts.sort((a, b) => b.data.pubDate.getTime() - a.data.pubDate.getTime() ）； const start = (pageNum - 1) * POSTS_PER_PAGE; const posts = SortedPosts.slice(start, start + POSTS_PER_PAGE); const TotalPages = Math.ceil(allPosts.length / POSTS_PER_PAGE); --- {posts.map(post =>

{post.data.title}

)} <导航> {pageNum > 1 && ← 上一页} 第 {pageNum} 页，共 {totalPages} {pageNum 下一页 →} ### 标签/类别档案为每个标签生成一个页面： --- // src/pages/tags/[tag].astro 从“astro：content”导入{getCollection}；导出异步函数 getStaticPaths() { const allPosts =等待 getCollection("博客"); const 标签 = new Set(); allPosts.forEach(post => post.data.tags?.forEach(tag => Tags.add(tag))); 返回 Array.from(tags).map(tag => ({ 参数：{标签}，道具：{标签}， })); } const { 标签 } = Astro.props; const allPosts =等待 getCollection("博客"); const postsWithTag = allPosts.filter(post => post.data.tags?.includes(tag)); ---

帖子标记：{tag}

{postsWithTag.map(post => {post.data.title})} ### RSS 源 // src/pages/rss.xml.js 从“@astrojs/rss”导入RSS；从“astro：content”导入{getCollection}；导出异步函数 GET(context) { const blog =等待 getCollection("blog"); 返回RSS（{ 标题：“我的博客”，描述：“关于 Astro 的博客”，站点：上下文.站点，项目：blog.map(post => ({ 标题：帖子.数据.标题，描述：post.data.描述， pubDate：post.data.pubDate，链接：`/blog/${post.slug}/`， }））， }); } ### 静态表格对于 SSG 站点，请使用第三方表单处理程序： **Formspree（最简单）：** <表单操作=“https://formspree.io/f/YOUR_FORM_ID”方法=“POST”> <输入类型=“文本”名称=“名称”必需/> <输入类型=“电子邮件”名称=“电子邮件”必需/> **Netlify 表格：**

出版 Astro 网站

包含技能