主页/WEB笔记/静态网站想加个后台管理，用Pages CMS搭配Astro能真香吗？

静态网站想加个后台管理，用Pages CMS搭配Astro能真香吗？

3,757字
16–24 分钟
in

静态网站生成器（SSG）这玩意儿，搞前端的朋友应该都不陌生。用Astro或Eleventy这类工具，刷刷刷就能撸出一个性能爆表的站点。可问题来了：内容更新怎么办？每次改个文章标题、换张配图，都得去扒拉Markdown文件，提交Git。非技术的小伙伴直接懵圈，更别提团队协作的时候，让运营同事去学Git分支合并？那画面太美不敢看。这时候就需要一个内容管理系统（CMS）来救场，但挑来挑去，要么收费套路深，要么配置复杂到想砸电脑。直到翻到Pages CMS——一个主打“零折腾”的开源方案，专门给静态站点用的。这货到底香不香？下面手把手走一遍把Pages CMS塞进Astro项目的全过程，顺便扒一扒那些容易翻车的细节。

目录

啥是Pages CMS

Pages CMS说白了就是一个基于Git仓库的轻量级后台。它没有数据库，内容全存成Markdown或JSON之类的纯文本文件，直接放在仓库里。认证方式支持GitHub账号或邮箱免密登录（俗称魔法链接），对非程序员相当友好。核心配置文件就一个.pages.config.yml，写清楚哪些文件夹能编辑、每个文档需要填什么字段（比如标题、日期、正文），它就会自动生成一个可视化后台界面。保存内容时，Pages CMS自动提交Git变更，连命令行都不用敲。

搭上Astro内容集合

Astro有个很爽的功能叫“内容集合”（Content Collections）。简单说，就是在src/content/下划个目录，比如blog，然后配一个schema（用Zod定义），Astro就会对目录里的所有Markdown文件做类型校验。举个例子，src/content.config.ts里这样写：

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

const blogCollection = defineCollection({
  loader: glob({ base: './src/content/blog', pattern: '**/*.md' }),
  schema: z.object({
    title: z.string(),
    summary: z.string(),
    publishDate: z.coerce.date(),
    coverImg: z.string().optional(),
  }),
});

export const collections = { blog: blogCollection };

这相当于告诉Astro：去src/content/blog里找所有.md文件，每个文件头部（frontmatter）必须包含title、summary、publishDate这几个字段，coverImg可有可无。一旦Pages CMS保存的内容不符合这个格式，Astro构建时就会报错，避免线上翻车。

搞定配置YAML文件

在项目根目录新建.pages.config.yml，这是Pages CMS的灵魂。需要定义两大部分：content（哪些内容可编辑）和media（图片等媒体文件扔哪儿）。下面拆开细说。

定义博客文章集合

content:
  - name: blog
    label: 博客文章
    path: src/content/blog
    filename: '{year}-{month}-{day}-{fields.title}.md'
    type: collection
    view:
      fields: [coverImg, title, publishDate]
    fields:
      - name: title
        label: 文章标题
        type: string
      - name: summary
        label: 摘要
        type: text
      - name: publishDate
        label: 发布日期
        type: date
        options:
          format: yyyy-MM-dd
      - name: coverImg
        label: 封面图
        type: image
      - name: body
        label: 正文
        type: rich-text

注意看filename那一行：{year}-{month}-{day}-{fields.title}.md，这表示保存文件时自动按“年-月-日-标题”的格式命名。这里有个坑：如果标题里有斜杠或中文，某些系统可能会出问题，建议提前在标题字段上加slugify选项（Pages CMS文档有说明）。另外path必须跟Astro内容集合的目录完全一致，否则保存的文件Astro读不到。

顺手管理站点全局配置

除了文章集合，还能把站点的一些通用设置做成可编辑的JSON文件。比如src/config/site.json里存着站点标题、描述、URL等：

  - name: site-settings
    label: 站点设置
    path: src/config/site.json
    type: file
    fields:
      - name: siteTitle
        label: 网站标题
        type: string
      - name: siteDesc
        label: 网站描述
        type: text
      - name: siteUrl
        label: 网站地址
        type: string
        pattern: ^https?://.+

这里type: file表示只编辑单个文件，而不是一个文件夹里的多个文档。pattern字段可以加正则校验，防止填错URL格式。保存后，Pages CMS会直接修改sit e.json的内容，然后提交Git。

媒体文件存储路径

media:
  input: public/media
  output: /media

input告诉Pages CMS把上传的图片存到public/media目录。output是个小技巧：因为Astro（底层Vite）已经知道public目录，图片引用路径里再写/public/media/xxx会报重复。设置output: /media后，Pages CMS在生成Markdown里的图片路径时会自动去掉public，变成/media/xxx。这样前端代码里直接<img src={frontmatter.coverImg}>就能正常显示。

连接线上后台

配置写完后，打开浏览器访问https://app.pagescms.org，用GitHub账号登录。授权时建议选“仅授权指定仓库”，避免Pages CMS乱翻其他项目。选好仓库（比如your-name/astro-blog-demo），点击项目名称进入仪表盘。左侧导航栏会出现“博客文章”、“站点设置”、“媒体库”等选项，完全由.pages.config.yml里的label决定。

上手发一篇文章

点击“博客文章”旁边的“添加条目”按钮，会弹出一个表单，每个字段都是之前配置过的：标题输入框、摘要文本框、日期选择器、图片上传按钮、富文本编辑器。填完内容后点“保存”，Pages CMS会干三件事：

  1. 根据filename模板生成一个新Markdown文件，比如2025-03-15-静态网站真香.md
  2. 把表单里的字段转成frontmatter格式写入文件头部，正文部分作为Markdown内容
  3. 自动执行git add、git commit并推送到远程仓库

全程不需要敲一行命令。如果仓库设置了自动部署（比如通过Netlify或Vercel监听main分支变更），提交后几分钟内站点就会更新。这里有个注意点：第一次配置Pages CMS时，需要确保仓库已经有.pages.config.yml文件且语法正确，否则后台会报错打不开。可以用yamllint之类的工具先检查一遍。

邀请队友一起干

点击左侧“协作者”菜单，输入对方的邮箱地址，系统会发一个免密登录链接（魔法链接）。收到邮件的人点一下链接就能进入后台，不用注册GitHub账号。适合让运营或文案同学直接上手改内容。权限上，所有协作者都能修改任意可编辑内容，目前Pages CMS没有更细粒度的权限控制，所以只适合信任的小团队。

另一种玩法：直接编辑JSON文件

除了博客文章这类集合，Pages CMS还支持直接编辑任何JSON或YAML文件。比如站点导航菜单的配置src/data/nav.json：

  - name: navigation
    label: 导航菜单
    path: src/data/nav.json
    type: file
    fields:
      - name: items
        label: 菜单项
        type: list
        fields:
          - name: text
            label: 显示文字
            type: string
          - name: link
            label: 链接地址
            type: string

这样后台会生成一个可动态增删的表单，用来维护导航链接。改完保存后，JSON文件自动更新，Astro构建时读取这个文件渲染导航栏。比起直接手改JSON，这种方式不容易把格式弄乱。

配置项作用常见坑点
typecollection或file混用会导致后台不显示
filename文件命名模板含特殊字符需转义
media.output图片引用路径前缀不匹配导致图片404
pattern字段正则校验写错正则导致无法保存

最后提一嘴，Pages CMS完全免费，开源，由单个开发者维护但接受PR。模板仓库已经传到GitHub，可以直接git clone下来跑。静态站点加后台这件事，用这套组合拳确实能省下不少头秃的时间。

最新发布