使用 Astro 构建一个轻量静态技术站

技术笔记站的主要工作，是把文章清楚地交给读者。对于没有账号、评论和在线交易的个人网站，可以先把内容保存为 Markdown，在构建时生成 HTML，再由 Web Server 提供静态文件。本站采用这个方案，下面结合当前目录说明具体做法。

为什么选择静态输出

文章只在编辑时变化，没有必要在每次访问时查询数据库。静态输出把模板渲染和内容校验放在构建阶段，服务器只负责返回文件。这样可以减少常驻服务，也让备份和回滚围绕一份完整产物进行。

这个选择也有边界：修改正文后需要重新构建和发布；依赖登录状态的个性化页面，需要另外设计。当前笔记站不提供这些功能，因此无需提前加入数据库或客户端框架。

让目录对应维护职责

本站将公共事实放在根目录的 site.config.ts，文章放在 src/content/notes/，页面路由放在 src/pages/。布局负责导航、页脚和 metadata，页面负责选择内容，样式保存在本地 CSS 中。

src/
├── content/notes/       # Markdown 正文
├── content.config.ts   # 集合入口
├── layouts/            # 共享页面结构
└── pages/notes/        # 列表与详情路由

不要在首页和列表页各维护一份文章数组。文章的标题、摘要与日期来自同一条集合记录，后续修改才不会出现“卡片改了，详情忘了改”的差异。

用内容集合管理 Markdown

Astro 提供构建时内容集合。本站使用 glob() 读取 Markdown，再由 schema 检查标题、摘要和日期。以下是缩小后的配置示例，实际规则以项目源码为准：

import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';
import { z } from 'astro/zod';

const notes = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/notes' }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    draft: z.boolean().default(false),
  }),
});

export const collections = { notes };

详情页通过 getStaticPaths() 为公开文章生成路由，再使用 render() 渲染正文。首页、列表和 sitemap 共用公开查询；draft: true 的文章不生成详情，也不进入这些发现入口。

草稿字段不是访问密码。需要保密的材料不应放进公开仓库；还要核对最终产物，避免把源文件或历史构建中的草稿一并上传。

从构建走向部署

本地先执行类型检查和构建，再用预览服务核对文章、内链、手机排版与 404。HTML 能生成，只能证明构建完成，不能证明域名解析、HTTPS 或线上状态码正确。

计划在 Lighthouse 上托管时，可以让 Caddy 或现有 Nginx 直接读取 dist/。每次发布保存完整版本，通过稳定目录切换到新版本，必要时恢复上一版本。服务器路径、证书与 DNS 应以实际环境为准。

本文记录本站的源码组织和部署思路。生产服务器发布尚待执行，不将部署计划写成线上实测结果。

为什么选择静态输出

让目录对应维护职责

用内容集合管理 Markdown

从构建走向部署

参考资料