十分钟搭建 Astro Tone
克隆、改一个配置文件、写一篇真实文章、部署。最短路径走完这个入门模板。
这个入门模板是一个小型 Astro 站点。读完本文,你的首页会显示你的名字,会有一篇真实文章,并且部署会指向你的域名。
不适用的步骤可以跳过。
安装#
npm create astro@latest my-posts -- --template hanityx/astro-tonecd my-postsnpm 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',}三条规则:
url是生产环境的源地址。只有部署在子路径下时才设置base,例如 GitHub Pages 的项目站点。title会显示在浏览器标签页和社交预览中。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% 后开启,接近顶部时恢复之前的主题。触发点由主题设定,与具体章节无关。
替换示例文章#
入门模板自带示例文章以展示版式。发布前请替换或删除它们。
最快路径:
- 若觉得这篇指南有用,可以保留。
- 删除
src/content/posts/中的其他示例。 - 添加三到四篇你自己的文章。
文章索引、RSS、相关文章和搜索会在下次构建时更新。
运行检查#
部署前:
npm run checknpm run buildnpm run previewcheck 运行 Astro 的类型检查。build 将静态站点和 Pagefind 搜索索引写入 dist/。preview 提供构建结果的本地预览,方便你点一遍。
如果 check 失败,先修复再部署。入门模板中的类型错误通常指向 astro-theme-config.ts 中缺少的字段。
部署#
Tone 构建到 dist/。大多数托管平台只需:
| Setting | Value |
|---|---|
| Build command | npm run build |
| Output directory | dist |
| Node | 22.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:
- 访问
https://giscus.app,选择一个已启用 Discussions 的仓库。 - 将其生成的四个值(
repo、repoId、category、categoryId)复制到config.comments.giscus。 - 将
config.comments.mode设为giscus(原版组件)或giscus-custom(Tone 风格组件)。
四个值都填齐后组件才会渲染。不存在「半启用」状态。
接下来读什么#
- 你会用到的 Markdown — 一页看完正文样式。
- 在一个文件里改外观 — 颜色、间距、字体。
- 何时使用 MDX — 在文章中内联使用 Astro 组件。