← 全部文章

十分钟搭建 Astro Tone

克隆、改一个配置文件、写一篇真实文章、部署。最短路径走完这个入门模板。

这个入门模板是一个小型 Astro 站点。读完本文,你的首页会显示你的名字,会有一篇真实文章,并且部署会指向你的域名。

不适用的步骤可以跳过。

安装#

Terminal window
npm create astro@latest my-posts -- --template hanityx/astro-tone
cd my-posts
npm run dev

开发服务器运行在 http://localhost:4321。如果端口被占用,Astro 会自动选择下一个可用端口并打印出来。

编辑一个配置文件#

打开 astro-theme-config.ts。全站设置只需改这一个文件。

site: {
url: 'https://your-site.com',
base: '',
title: 'Your Site',
logoLabel: 'Tone',
description: 'One short line about the site.',
author: 'Your Name',
defaultOgImage: '/og.png',
}

三条规则:

  1. url 是生产环境的源地址。只有部署在子路径下时才设置 base,例如 GitHub Pages 的项目站点。
  2. title 会显示在浏览器标签页和社交预览中。
  3. logoLabel 是页头中首页链接旁的文本。保持简短——它位于 52px 高的栏内。

其他字段可以稍后再填。

了解文件位置#

入门模板把公开界面保持得很小。大多数改动发生在以下位置之一:

src/
assets/ Sample images and fonts
components/ Astro components
content/posts/ Markdown and MDX posts
layouts/ Shared layouts
pages/ Routes
scripts/ Client-side behavior
styles/ Tokens, prose, page, layout, and shared behavior CSS
ui.ts Shared UI labels
LICENSE License and third-party notices

先改 astro-theme-config.ts。需要调整全站样式、正文排版、页面布局或共享行为时,再动 src/styles/。需要改组件结构或组件自有样式时,再动 src/components/。

决定页头显示什么#

nav 默认为空。Logo 链接到首页,主题切换在右侧,仅此而已。

如果需要页头链接:

nav: [
{ label: 'Posts', href: '/posts' },
{ label: 'About', href: '/about' },
],

页脚链接在 footerNav 中,始终可见。安静的页头配上实用的页脚,也是不错的选择。

写第一篇文章#

文章放在 src/content/posts/。文件名会成为 URL 的 slug。

创建 src/content/posts/hello.md:

---
title: 'Hello'
description: 'A first post to test the layout.'
pubDate: '2026-05-01'
category: 'Notes'
---
This is the first paragraph. Start with a concrete note, a small decision, or one thing you want to remember.

必填项:title、description、pubDate。其余均为可选。

  • draft: true 会让文章不出现在构建结果、RSS 订阅和搜索索引中。
  • category 驱动 /posts 上的筛选行。从 config.content.categoryOrder 中选择,或添加新分类。
  • heroImage 是 src/assets/ 内文件的相对路径。它用于卡片、社交元数据和结构化数据;若文章需要在正文中内联显示图片,也请把图片放在 Markdown 正文里。
  • homeHeroOrder: 1 将文章固定到首页顶部的两个紧凑链接之一。数字越小越靠前;未固定的文章按发布日期填充空位。
  • homeFeatured: true 将一篇文章固定到首页的大特色卡片。
  • homeOrder: 1 将文章固定到首页网格。数字越小越靠前;未固定的文章按发布日期填充空位。
  • focusEffect: 'scroll-dark' 为该文章启用可选的滚动深色效果。读者滚动过正文大约前 20% 后开启,接近顶部时恢复之前的主题。触发点由主题设定,与具体章节无关。

替换示例文章#

入门模板自带示例文章以展示版式。发布前请替换或删除它们。

最快路径:

  1. 若觉得这篇指南有用,可以保留。
  2. 删除 src/content/posts/ 中的其他示例。
  3. 添加三到四篇你自己的文章。

文章索引、RSS、相关文章和搜索会在下次构建时更新。

运行检查#

部署前:

Terminal window
npm run check
npm run build
npm run preview

check 运行 Astro 的类型检查。build 将静态站点和 Pagefind 搜索索引写入 dist/。preview 提供构建结果的本地预览,方便你点一遍。

如果 check 失败,先修复再部署。入门模板中的类型错误通常指向 astro-theme-config.ts 中缺少的字段。

部署#

Tone 构建到 dist/。大多数托管平台只需:

SettingValue
Build commandnpm run build
Output directorydist
Node22.12 or newer

Vercel、Netlify 和 Cloudflare Pages 都能自动识别 Astro。导入仓库,接受默认设置,然后部署。

首次上线后,把 astro-theme-config.ts 中的 site.url 设为真实域名并重新部署。规范链接、RSS、站点地图和社交预览都依赖它。

如果部署在子路径下,例如 username.github.io/repo,发布前在 astro-theme-config.ts 中设置 site.base。Astro 配置会读取该值。

内置的 GitHub Pages 工作流会为项目页面自动设置 ASTRO_SITE_URL 和 ASTRO_SITE_BASE。例如,名为 my-posts 的仓库会部署到 /my-posts;名为 username.github.io 的用户站点仓库会部署到域名根路径。

启用评论(可选)#

评论默认关闭。要启用 giscus:

  1. 访问 https://giscus.app,选择一个已启用 Discussions 的仓库。
  2. 将其生成的四个值(repo、repoId、category、categoryId)复制到 config.comments.giscus。
  3. 将 config.comments.mode 设为 giscus(原版组件)或 giscus-custom(Tone 风格组件)。

四个值都填齐后组件才会渲染。不存在「半启用」状态。

接下来读什么#

  • 你会用到的 Markdown — 一页看完正文样式。
  • 在一个文件里改外观 — 颜色、间距、字体。
  • 何时使用 MDX — 在文章中内联使用 Astro 组件。