本地开发Starlight

新建文档

通过在 src/content/docs/ 目录中创建 Markdown 文件来为你的网站添加新页面。

本地开发

使用 Wrangler 对你的项目进行本地预览，这个会在本地模拟 cloudflare 依赖模块。

npx astro build && npx wrangler dev

如何使用 Astro 的开发服务器

先将astro.config.mjs文件中的cloudflare模块注释

import cloudflare from '@astrojs/cloudflare';

  adapter: cloudflare({
    imageService: { build: 'compile', runtime: 'passthrough' }
  }),

然后使用 Astro 的开发服务器来预览你的 Starlight 应用，在你进行更改时自动刷新你的浏览器：

npm run dev

当准备发布时，将注释掉的 Cloudflare 模块取消注释，然后更新内容就可以上传到绑定的GitHub仓库。

‘astro’ 不是内部或外部命令，也不是可运行的程序

npm install

不绑定 Cloudflare image 服务

参考链接：astro 文档

修改astro.config.mjs文件，添加以下内容：

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({
    imageService: { build: 'compile', runtime: 'passthrough' }
  }),
});

这将禁用 Cloudflare image 服务，使你能够在本地开发和测试 Starlight 应用，而不依赖于 Cloudflare 的图像处理功能。

侧边栏导航恢复成默认侧边栏

参考链接：默认侧边栏

新建的 Starlight 项目默认使用了定义好的侧边栏导航，所以新建出来的项目侧边栏导航是固定的，如果你想要恢复成默认侧边栏导航，可以修改 astro.config.mjs 文件，将以下内容进行注释或删除。

sidebar: [
    {
        label: 'Guides',
        items: [
            // Each item here is one entry in the navigation menu.
            { label: 'Example Guide', slug: 'guides/example' },
        ],
    },
    {
        label: 'Reference',
        autogenerate: { directory: 'reference' },
    },
],

后续 Starlight 会根据你的文档文件系统结构自动生成侧边栏，使用每个文件的 title 属性作为侧边栏条目。

侧边栏导航自定义排序权重

在单个页面中使用 sidebar 字段来自定义自动生成的链接。

侧边栏 frontmatter 选项允许你设置自定义标签或者为链接添加徽章，隐藏侧边栏中的链接，或者定义自定义排序权重。

---
title: 我的页面
sidebar:
  # 为链接设置自定义标签
  label: 自定义侧边栏 label
  # 为链接设置自定义顺序（数字越小显示在上方）
  order: 2
  # 为链接添加徽章
  badge:
    text: New
    variant: tip
---

控制页脚是否显示页面上次更新的时间

参考链接：lastUpdated

控制页脚是否显示页面上次更新的时间。

默认情况下，此功能依赖于你的存储库的 Git 历史记录，并且在某些执行浅克隆的部署平台上可能不准确。页面可以使用 lastUpdated frontmatter 字段覆盖此设置或基于 Git 的日期。

export default defineConfig({
  integrations: [
      starlight({
          title: 'My Docs',
          lastUpdated: true,
      }),
 ],
});

修复页面不显示上次更新的时间问题1-生效一点点

参考链接：解决Github action与Cloudflare page打包时git提交记录获取不全问题) 如何使 Cloudflare Pages 显示文档的创建和修改时间

git fetch --unshallow && npx astro build

修复页面不显示上次更新的时间问题2-未成功

使用修复方式1还是不行，仔细看了下有一条日志提示。

[wrangler:warn] The latest compatibility date supported by the installed Cloudflare Workers Runtime is "2026-03-10",
but you've requested "2026-03-13". Falling back to "2026-03-10"...
Features enabled by your requested compatibility date may not be available.
Upgrade to `wrangler@4.76.0` to remove this warning.

然后更新了一下wrangler就正常显示了，从^4.72.0 升级到 ^4.76.0。

npm install wrangler@4.76.0

修复页面不显示上次更新的时间问题3-成功版

问题原因

在 Cloudflare Pages 构建环境中，Git 默认使用转义序列输出非 ASCII 路径（如中文），导致 Starlight 无法正确解析文件路径。只有 index.mdx 能获取时间是因为它的路径没有中文字符。

使用1的修复方式为文件获取正确的更新时间，然后再构建命令替换成以下内容。

git config core.quotepath false && git fetch --unshallow && npx astro build

  {"scripts":
    "build": "git config core.quotepath false && astro build"
    }

控制是否启用workers.dev和预览URL

参考链接：Disabling workers.dev in the Wrangler configuration file

{
  "workers_dev": false
}