便笺: Astro 7 双仓库机制研究(主题代码仓库 + 独立内容仓库)

Published 2026-11-04 20:28 Updated 2026-11-04 20:38 4468 words 23 min read

kissablecho avatar

kissablecho

Kissablecho's personal blog — recording life, sharing technology, anime & white stockings enthusiast.

This post is not yet available in English. Showing the original.
研究任务:task-1 | 环境:Windows 11 + Node v24.18.0 + pnpm 12.9.1 + astro 7.4.5 + vite 8.3.5(rolldown-vite) 证据:根项目实测( / / dev 均通过)、 隔离实验、 源码、Astro 官方文档(以 v7 文档为准) 标注:[已验证] = 运行或源码确认;[推测] = 源码推断、未直接运行验证。...

研究任务:task-1 | 环境:Windows 11 + Node v24.18.0 + pnpm 12.9.1 + astro 7.4.5 + vite 8.3.5(rolldown-vite)

证据:根项目实测(astro sync / pnpm build / dev 均通过)、experiments/astro7/** 隔离实验、node_modules/astro/dist/** 源码、Astro 官方文档(以 v7 文档为准)

标注:[已验证] = 运行或源码确认;[推测] = 源码推断、未直接运行验证。

结论先行:该方案在 Astro 7.4.5 上可行,根项目已落地;关键约束是 glob base 必须是相对 config.root 的 POSIX 路径、内容仓库 site.config.ts 只能使用可擦除 TS 语法、自定义模式开关必须用环境变量而非 CLI 参数。

0. 结论速览

#问题结论状态
1外部内容目录怎么接glob({ base: <相对项目根的 POSIX 路径> }) 可用;file() 只适合单文件;跨盘符不可用[已验证]
2配置加载 / Node 原生 TSastro.config.mjs 由 Node 原生 import() 加载,TLA / process.env / process.argv 全可用;外部 .ts 可用 Node 24 strip-types 直接 import(enum 除外);defineConfig 不支持 async 工厂[已验证]/[推测]
3updateConfig 的 vite.defineintegration 在 astro:config:setup 调 updateConfig({vite:{define,...}}) 会合并进 Vite 配置,对 src/content.config.ts 生效;但只做静态文本替换[已验证]
4virtual
integration 注册 Vite plugin(Astro 7 无 addVitePlugin),dev/build 均可用;需 env.d.ts 手写类型[已验证]
5CLI 未知参数yargs-parser 静默接受、不报错;--background 子进程只转发白名单 flag,自定义参数会丢[已验证]
6dev —background7.0+ 内置 astro dev --background/stop/status/logs;Windows 不会自动后台,须手动加 flag[已验证]
7site 动态化影响sitemap/rss/canonical 全部只读 config.site;config 阶段算好 site 即可,无需改代码[已验证/源码]
8官方分离实践官方无「内容仓库」概念;本地/远程 loader 均可,外部本地目录即 glob(base)[已验证/文档]

1. 内容来源:glob() / file() / 自定义 loader

1.1 glob():从项目根之外读取文章 [已验证]

// src/content.config.ts(根项目实际实现)
const blogBase = resolveBlogBase(); // 返回相对项目根的 POSIX 路径,如 '../content/posts'
export const collections = {
  blog: defineCollection({
    loader: glob({ base: blogBase, pattern: '**/*.{md,mdx}' }),
    schema: ({ image }) => z.object({ title: z.string(), pubDate: z.coerce.date() }),
  }),
};
  • base 在源码里是 new URL(base, config.root) 解析(node_modules/astro/dist/content/loaders/glob.js:186),所以默认相对 项目根,也可传 file:// URL 或绝对路径(文档:string | URL)。
  • pattern 不能以 / 或 ../ 开头(glob.js:53,56 抛 “Glob patterns cannot start with …”,要求改用 base)。
  • 文件可位于项目根之外:内部用 posixRelative(config.root, filePath)(glob.js:110)记录为 ../content/posts/x.md,entry id 仍相对 base;watcher.add(filePath)(glob.js:250)注册监听。
  • Windows 关键坑:不能把 C:\...\posts 绝对路径字符串传给 base(new URL('C:\...', root) 会解析成 c: scheme)。正确做法是 path.relative(rootDir, postsDir).split(path.sep).join('/');path.isAbsolute(relativePath) 为真(跨盘符)时无解,必须抛错或换方案。
  • dev 下访问项目根之外的文件,需要 vite.server.fs.allow 包含内容仓库目录(见 §4)。

1.2 file():单文件集合 [已验证/源码]

  • fileName 同样是 new URL(fileName, config.root),且不能含 *(否则 FileGlobNotSupported);支持 JSON / YAML / TOML,或用 options.parser 自定义。
  • 数据必须是「含唯一 id/slug 的对象数组」或「id → entry 对象」;文件缺失只 logger.error 不抛错;无扩展名/无 parser 抛 FileParserNotFound。
  • 结论:适合内容仓库只有一份数据文件(如导航/配置)的场景,不适合文章集合(无 markdown 渲染、无 per-file schema 元数据)。

1.3 自定义 loader [文档]

  • 文档明确 loader 可”load data from any source, local or remote”;远程内容(CMS)需要自定义 loader 或社区 loader,Astro 7 无内置远程 loader。
  • 简单场景可直接写 async 函数返回数组/对象;复杂场景用 object loader API 自己维护 store/id/digest/watch。
  • 建议:文章用 glob()(根项目已验证主题/内容两种模式构建通过);站点配置不用 loader,直接在 config 阶段 import .ts 更简单(见 §2)。

2. astro.config.mjs 的加载与 Node 24 原生 TS

2.1 加载机制 [已验证/源码]

node_modules/astro/dist/core/config/vite-load.js:

  • 路径匹配 /\.[cm]?js$/(.mjs/.js/.cjs)→ Node 原生 await import(pathToFileURL(configPath) + '?t=' + Date.now())(
    ),同进程执行。
  • 其他(.ts/.mts)→ 起 minimal Vite server,用 environment.runner.import(configPath) 在 Vite SSR 里执行(
    )。
  • 即:Astro 不走 Vite 的 loadConfigFromFile(create-vite 里 configFile: false,core/create-vite.js),而是自己实现「.mjs → Node 原生 import / .ts → Vite runner」。
  • 所以:保持 astro.config.mjs,才能 100% 保证 top-level await、process.env、process.argv、Node 原生 TS import 等能力;.ts 配置虽然一般也能跑,但执行环境换成 Vite runner,行为受 Vite 控制。

2.2 top-level await 与 async 工厂 [已验证]/[推测]

  • TLA 可用:根项目 astro.config.mjs 顶层 const context = await loadSiteContext(root),astro sync / pnpm build 均通过。
  • defineConfig 是同步恒等函数:function defineConfig(config)(dist/config/index.js:5-7),类型签名也只接受对象。export default async () => ({...}) 不支持 [推测]:loadConfig 直接取 mod.default,随后 mergeConfigRecursively({...defaults}, userConfig) 用 for...in 遍历,函数没有可枚举自有属性 → 配置被当成空对象;类型层面也会报错。
  • 需要异步时用 TLA,不要用 async 工厂。

2.3 内容仓库 site.config.ts 用 Node 24 直接 import [已验证]

  • 根项目 scripts/site-config.mjs 用 await import(pathToFileURL(file).href) 加载 <content-repo>/site.config.ts,取 mod.default ?? mod.siteConfig ?? mod.themeSiteConfig,并在 config 阶段校验(title/description/url 合法性等)。
  • Node 24.18 的 strip-only 类型擦除实测(experiments/astro7/_cache/ts-test/,node --input-type=module -e "await import('./x.ts')"):
    • import type 擦除:OK;satisfies SiteConfig:OK;interface + 普通 const:OK。
    • export enum Mode {}:SyntaxError: TypeScript enum is not supported in strip-only mode。
  • 因此内容仓库 site.config.ts 的写法约束:
    1. 只能用可擦除语法:interface / type / import type / satisfies / 普通 const;不要 enum、namespace、构造器参数属性。
    2. 类型复用只能 import type(编译/擦除后不产生运行时 import)。若内容仓库不在主题仓库目录内,跨仓库相对路径不稳定 → 推荐「主题导出类型 + 内容仓库复制/生成一份类型声明」或 type-only 引用发布到包(type-researcher 的 task-2 方向)。
    3. 避免任何运行时 import(含值 import):内容仓库通常没有 node_modules,Node 解析不到依赖会失败。

3. integration 的 updateConfig({ vite }) 生效范围

3.1 合并链路 [已验证/源码]

  • astro:config:setup 在 Vite server 创建之前执行(dist/integrations/hooks.js:105 runHookConfigSetup);钩子内的 updateConfig 实现为 mergeConfig(updatedConfig, newConfig)(hooks.js:168-174)。
  • dist/core/create-vite.js:332 注释给出合并顺序:1 common → 2 user vite → 3 integration config
    → 4 command config;
    依次 vite.mergeConfig。
  • 因此 updateConfig({ vite: { define, plugins, server: { fs: { allow } }, resolve: { alias } } }) 全部有效,并作用于后续所有 Vite 转换模块(src/**、src/content.config.ts、虚拟模块、astro environment runner)。Vite 官方 mergeConfig 对 define/alias 按键级合并/覆盖。

3.2 define 能进 content.config.ts 吗?能 [已验证]

  • content 配置加载链:dev 预热 kickOffContentConfigLoad(dist/content/config-prewarm.js:14)→ loadContentConfig(dist/content/utils.js:304)→ environment.runner.import(configPathname)(:310);环境是 ASTRO_VITE_ENVIRONMENT_NAMES.astro(types-generator.js:66),即 create-vite.js:315-317 注册的 { astro: { dev: {} } } RunnableDevEnvironment。
  • 隔离实验 experiments/astro7/flags-test/:integration 在 config
    里 updateConfig({ vite: { define: { __PROBE_DEFINE__: JSON.stringify('define-ok') } } }),src/content.config.ts 顶层断言 __PROBE_DEFINE__ === 'define-ok' 否则 throw;astro sync 与 astro build --content foo 均 exit 0,内容 loader 正常执行 → define 先于 content.config 加载生效。
  • 限制:define 只是编译期文本/表达式替换,只匹配源码里出现的字面量(如 import.meta.env.X、自定义全局标识符),无法代理运行时 process.env.X 读取。

3.3 根项目的选择

  • 根项目 astro.config.mjs 的 integration 在 config
    执行 updateConfig({ vite: { plugins: [siteConfigPlugin()], server: { fs: { allow: devServerAllow } } } });devServerAllow = [项目根] + 内容仓库目录(项目内则不重复)。
  • 不用 vite.define 传站点配置:虚拟模块能传对象、有类型、能 watch 文件,优于 define 字符串替换。

4. 虚拟模块 virtual

4.1 注册方式(Astro 7 无 addVitePlugin)[已验证]

// astro.config.mjs(根项目做法)
function siteConfigIntegration(context) {
  return {
    name: 'site-config',
    hooks: {
      'astro:config:setup': ({ updateConfig }) => {
        updateConfig({ vite: { plugins: [siteConfigPlugin(context)], server: { fs: { allow } } } });
      },
    },
  };
}
  • Astro 7 的 astro:config:setup 钩子没有 addVitePlugin(types/public/integrations.d.ts 的 hooks 列表里没有;实测调用报 “addVitePlugin is not a function”),必须走 updateConfig({ vite: { plugins } })。

4.2 插件实现与 dev watch [已验证]

const ID = 'virtual:site-config'; const RESOLVED = '\0' + ID;
function siteConfigPlugin(context) {
  return {
    name: 'virtual-site-config',
    resolveId(id) { if (id === ID) return RESOLVED; },
    load(id) {
      if (id !== RESOLVED) return;
      this.addWatchFile(path.resolve(context.siteConfigFile)); // dev 下文件变更触发虚拟模块失效
      return `export const contentSource = ${JSON.stringify(context.contentSource)};\n` +
        `const siteConfig = ${JSON.stringify(context.siteConfig)};\nexport default siteConfig;`;
    },
  };
}
  • 应用侧:src/config/index.ts import siteConfig, { contentSource } from 'virtual:site-config';src/env.d.ts 写 declare module 'virtual:site-config' 供 TS 检查(pnpm check 通过)。
  • 实测:根项目 dev + build 两种模式全部通过(theme 8 页 / content 6 页,dev curl 返回正确 HTML);隔离实验 flags-test 的 virtual:probe-config build 后 dist/index.html 中 virtual=True define=True。
  • 变体:load 返回 export * from '<绝对路径>/content/site.config.ts'。[推测] dev/build 理论可行(Vite 会继续解析该绝对路径 .ts 并走 esbuild/rolldown transform),但本环境只在 experiments/astro7/dual-repo/theme 验证到 config 阶段(该嵌套项目卡在 yaml 问题上,未完成 build),未完成端到端验证;且会引入项目外 .ts 的 tsconfig 归属、server.fs.allow、HMR 边界问题 → 推荐运行时值内联(JSON)(根项目已验证)。

5. CLI 参数行为

5.1 未知 flag 静默忽略 [已验证]

  • 解析:dist/cli/index.js:206-210 yargs(argv, { boolean: ['global'], alias: { g: 'global' } }),未知 flag 原样进入 flags(yargs-parser 默认不校验);命令解析只看 flags._[2] 是否在白名单(
    ),未知命令回落 help。
  • 实测:astro build --content foo exit 0、构建正常;astro.config.mjs 中 process.argv.slice(2) 可见 ["build","--content","foo"](隔离实验 flags-test)→ 可在 config 里自行解析自定义参数。
  • 官方没有「注册自定义 CLI flag」的 API;dist/cli/flags.js:4-27 flagsToAstroInlineConfig 只映射 12 个内置 flag(root/config/port/host/site/base/outDir/mode/verbose/silent/force/allowedHosts/json)。

5.2 —root / —config [已验证/源码]

  • --root 指定项目根(用于寻找配置、解析相对路径);--config 相对项目根(dist/core/config/config.js:38-52,找不到抛 ConfigNotFound)。
  • 配置搜索顺序:astro.config.mjs → .js → .ts → .mts(config.js:21-26)。

5.3 ⚠ 后台模式的参数转发白名单(重要)

  • dist/cli/server.js:43-71 buildBackgroundArgs 只转发:—port/—host/—config/—root/—allowed-hosts/—json/—mode/—site/—base/—out-dir/—verbose/—silent/—open。
  • 因此 astro dev --background --content foo 里 --content foo 不会传给后台子进程;自定义模式开关必须用环境变量(根项目用 CONTENT_REPO)或写进 config 可见的位置。
  • 建议:环境变量驱动(CONTENT_REPO=content pnpm dev),CLI 参数只做「前端糖」:在 astro.config.mjs 读 argv 后转成内部 context,不要依赖它传进后台。

6. dev server background(Astro 7 内置)

  • 用法:astro dev --background;astro dev status、astro dev logs [--follow]、astro dev stop(7.0+,文档 cli-reference “Background dev server”;preview 于 7.2.0+ 支持)。
  • 状态/日志位置:lock 文件 <root>/.astro/dev.json(dist/core/dev/lockfile.js:10),日志 <root>/.astro/dev.log(
    );额外 --json 输机器可读日志(7.0.0),--force 停旧起新,--ignore-lock 忽略锁。
  • stop 流程:SIGTERM → 等 5s(GRACEFUL_SHUTDOWN_TIMEOUT=5e3,
    )→ SIGKILL(
    )。
  • Windows 注意:dist/cli/agent.js 的 supportsAgentAutoBackgrounding 对 win32 返回 false(注释:detached 子进程会留在 agent 的 Windows Job Object 里,随 agent 终止,astro#18019)→ Windows 上不会自动后台,必须手动 --background,且后台进程仍可能随 agent 会话结束被杀 [风险]。
  • 实测:根项目 .astro/dev.json 存在(background: true, port: 4341),两种模式 dev 启动后 curl 返回正确 HTML [Lead 已验证]。
  • agent 环境 smoke test 建议:astro dev --background --port <空闲端口> → 轮询 .astro/dev.json 或 astro dev status 直到 ready → curl http://localhost:<port>/ 校验预期 HTML → astro dev logs --lines 50 看错误 → astro dev stop;避免与已有 dev(如 4341)抢端口,并注意 Windows 上 detached 子进程可能随 agent 结束。

7. site 动态化的影响(sitemap / RSS / canonical)

  • site 来自 astro.config.mjs 的 site 字段;根项目在 config 阶段把它设为 context.siteConfig.url,两种模式自然得到不同 site。
  • canonical:src/components/BaseHead.astro new URL(Astro.url.pathname, Astro.site) → <link rel="canonical">、OG og:url、RSS alternate 链接全部随之变化。构建产物已验证(dist/index.html canonical = https://example.com/)。
  • @astrojs/sitemap@3.7.4:if (!config.site) 时 warn “The Sitemap integration requires the site astro.config option. Skipping.”(dist/index.js
    );finalSiteUrl = new URL(config.base, config.site)(
    );页面 loc = new URL(fullPath, finalSiteUrl)(
    /75)。→ 只要 config.site 正确,输出自动正确,无需改代码。
  • @astrojs/rss@4.0.19:site 是必填 URL(dist/index.js
    zod),channel.link / item.link 用 createCanonicalURL(site, trailingSlash, ...)(
    /
    )。根项目 src/pages/rss.xml.js 用 site: context.site;Astro.site 缺失时 rss() 会直接报错,因此 site 必须始终有值。
  • 切换模式时 site 变化 → content layer 检测 “Astro config changed” 并 “Clearing content store” 后重新 sync(Lead 实测);构建产物建议两模式用不同 --out-dir(如 dist / dist-content)或分 CI job,避免互相覆盖(当前默认都是 dist)。
  • 结论:sitemap/RSS/canonical 不需要任何双仓库改造,唯一要求是 astro.config.mjs 的 site 在 config 阶段算对。

8. 官方「内容与代码分离」实践(v7 文档)

9. 风险与未验证项

  1. 跨盘符:path.relative 后仍为绝对路径(内容仓库在另一个盘)时无解,根项目已显式 throw;方案要求同盘(不同目录可以)。
  2. process.cwd() vs config.root:根项目 src/content.config.ts 用 process.cwd() 解析路径;从其他 cwd 启动(如 astro --root、monorepo filter)时可能不一致,更稳的是基于 config.root/文件 URL 推导 [风险,未验证]。
  3. dev watch 项目外目录:glob loader 会 watcher.add 外部文件,但 Windows 下 chokidar/rolldown watch 项目外目录的可靠性未验证(根项目 dev 两种模式已能跑,未做「改外部 md 热更新」专项测试)。
  4. 嵌套子项目实验失败:无自身 node_modules 的嵌套最小项目在 sync 时,Vite 8 ModuleRunner 会把根 node_modules 的 CJS yaml 内联执行,报 require is not defined(仅 astro/loaders 触发;flags-test 不 import loaders 故正常)。根项目(自身有 node_modules)不受影响,勿据此判定环境不可用;experiments 结论以根项目实测为准。
  5. Node TS 语法:内容仓库 site.config.ts 不能用 enum/namespace/参数属性;值 import 依赖 Node 解析路径/包,内容仓库没有 node_modules 时失败。
  6. 虚拟模块类型手写:src/env.d.ts 的 module 声明需与 plugin load 内容保持一致;不同步时 astro check 可能通过但运行时出错。
  7. site 变化导致 content store 清空:属预期行为,但频繁切换模式会重复 sync;两种模式的 dist 会互相覆盖(需分 outDir)。
  8. Windows agent 后台 dev:手动 --background 可用,但 detached 子进程可能随 agent Job Object 终止(astro#18019 注释),长驻 dev 需宿主自行管理。
  9. sitemap/RSS 在「site 为空」时的行为已由源码确认(sitemap 跳过、rss 抛错);本方案 config.site 始终有值,未实际跑空 site 实验。

10. 复现与证据索引

  • 根项目落地文件:astro.config.mjs(TLA + loadSiteContext + integration + virtual
    + sitemap/mdx/fonts)、scripts/site-config.mjs(读 CONTENT_REPO → 加载/校验外部 site.config.ts)、src/content.config.ts(glob base 解析 + schema)、src/config/site.ts(SiteConfig 类型 + 默认配置)、src/config/index.ts(虚拟模块消费)、src/env.d.ts(虚拟模块类型)。
  • 隔离实验:experiments/astro7/flags-test/(integration updateConfig define 注入 content.config.ts + virtual
    + process.argv 观察;运行脚本 experiments/astro7/_cache/flags-test.ps1、virtual-test.ps1);experiments/astro7/_cache/ts-test/(Node 24 原生 TS import 三例:only-types/satisfies/enum);experiments/astro7/_cache/{content-loader-reference,content-collections,configuration-reference,integrations-reference,cli-reference,upgrade-to-v7}.md(文档缓存)。
  • 源码锚点(均在 node_modules/astro/dist/ 下):config/index.js:5、core/config/vite-load.js:10,31、core/config/config.js:21,38、core/config/merge.js:9、content/loaders/glob.js:53,110,186,250、content/loaders/file.js、content/utils.js:304,482、content/types-generator.js:66、content/config-prewarm.js:14、integrations/hooks.js:105,168、core/create-vite.js:315,332,365、cli/index.js:3,206、cli/flags.js:4、cli/dev/index.js:69、cli/server.js:43,84、cli/agent.js、core/dev/lockfile.js:5,10,16,175、vite-plugin-environment/index.js:8,36。
  • 运行时验证命令(Windows,pwsh,workdir=项目根):node node_modules/astro/bin/astro.mjs sync;pnpm build;CONTENT_REPO=content pnpm build;astro dev --background 后 astro dev status/logs/stop。

11. Lead 最终实现补记(2026-11-04 13
,交付前)

  • 参数方案落地:本模板支持 --content / --content-repo[=DIR] / --theme;astro.config.mjs 的前台 argv 解析保留(直接 pnpm exec astro build --content 可用),另外新增包装器 scripts/astro.mjs(package.json 的 dev/build/preview/check 都经它启动),把同样的参数转成 CONTENT_REPO 环境变量后再 spawn Astro。
  • 原因(与 §6 的 CLI/后台结论对应):astro dev --background 的父进程不加载用户的 astro 配置,而 buildBackgroundArgs() 只转发白名单参数(node_modules/astro/dist/cli/server.js:43-71),随后用 启动 detached 子进程(server.js
    )。所以 pnpm dev --content --background 若只靠配置里读 argv 会退回主题模式;改成环境变量后父进程、后台子进程都能继承 → [已验证] 后台 dev 日志 [site-config] 内容来源: content (CONTENT_REPO=content, 目录: content),页面 lang="zh-CN"。
  • 补充一个 §6 smoke test 建议的修正:Astro 7 后台 dev 在 Windows 上只监听 IPv6 [::1]:4321(netstat -ano 实测),curl 必须用 http://localhost:4321;用 127.0.0.1 会 ECONNREFUSED。
  • [已验证] 前后台两模式矩阵:pnpm dev --background(theme,200,lang="en")、pnpm dev --content --background(content,200,lang="zh-CN");pnpm build 8 页、pnpm build --content 6 页、CONTENT_REPO=content pnpm build --theme 8 页(--theme 优先级正确);astro dev stop 正常停止。

12. Lead 补记:内容仓库页面与 MDX layout(2026-11-04 13
)

  • 需求:研究 content/posts 的 MDX 能否 import,以及把 src/pages/*.{md,mdx} 这类独立页面迁移到内容仓库 content/pages。
  • MDX 自动应用 layout 的源码位置:@astrojs/mdx 8.1.2 的默认 processor 是 satteri(node_modules/@astrojs/mdx/dist/index.js
    let processor = configuredProcessor ?? satteri());真正的注入在 @astrojs/markdown-satteri/dist/mdx/create-processor.js:98-117:当 resolvedFrontmatter.layout 存在时,在编译结果里追加 import __astro_layout_component__ from <layout>,并让 export default function MDXContent(props) 用 __astro_layout_jsx__(__astro_layout_component__, {file,url,content:frontmatterContent,frontmatter:frontmatterContent,headings,commands,'server:root':true,children}) 包一层。layout 说明符按该 mdx 文件的相对路径交给 Vite 解析(@astrojs/mdx/dist/vite-plugin-mdx.js:33-41 transform 后由 Vite resolve)。因此内容集合里的 .mdx 也会应用 layout,且可用别名(本模板 @theme)。
  • .md 页面不套 layout:node_modules/astro/dist/vite-plugin-markdown/index.js:88-89 注释明确 layout only applies to Markdown pages and direct imports, not content collection entries;实现为 const layout = hasContentFlag(id, MARKDOWN_CONTENT_ENTRY_FLAG) ? undefined : frontmatter.layout;。内容集合里的 .md 页面仍生成路由,但不会应用 frontmatter.layout;需要布局请用 .mdx。
  • 布局收到原始 frontmatter:MDX layout 的 props 为 {file,url,content,frontmatter,headings,‘server
    ’,children},frontmatter 来自 YAML 原文(date 是字符串,不是 schema 的 z.coerce.date());布局里要自己 new Date() 归一化。首次构建的 TypeError: date.toISOString is not a function 即由此产生,已在 PageLayout 的 dateValue 修复。
  • 路由设计:新增 pages 集合(glob base 随模式切换:主题 ./src/content/pages,内容 <内容仓库>/pages),src/pages/[...slug].astro 用 getCollection(‘pages’) 生成 /<id>;因为 MDX 已自动包布局,路由模板只渲染 <Content />,避免双层布局。[已验证] 产物中 class=“date” 只出现 1 次。
  • 导入验证:content/posts/mdx-showcase.mdx 里 import { Span } from '@ui' 与相对路径 import RelativeSpan from '../../src/components/ui/Span.astro' 均构建通过、组件渲染;内容页面同样可用 @ui。@ui = src/components/ui/index.ts,@theme = src 目录,由 astro.config.mjs 的 vite.resolve.alias 与根 tsconfig paths 同时提供。
  • 验证数字(2026-11-04,Node 24.18 / pnpm 12 / Astro 7.4.5):[已验证] pnpm build(theme)9 page(s)(新增 src/content/pages/welcome.mdx),pnpm build:content 8 page(s)(含 /playlist、/theme-layout),pnpm check 26 files 0 errors/0 warnings/0 hints;dev content 模式 /playlist 与 /theme-layout 均 200 且布局/日期/评论区占位/ui-span 正常;后台 dev 仍只监听 IPv6,需用 http://localhost:4321。
  • 落地文件:astro.config.mjs(@theme 别名)、tsconfig.json(paths @theme/*)、src/pages/[…slug].astro(只渲染 Content)、src/layouts/PageLayout.astro(主题可复用布局)、content/layouts/PageLayout.astro(内容仓库布局)、content/pages/{playlist,theme-layout}.mdx、src/content/pages/welcome.mdx、src/components/ui/{Span.astro,index.ts}。

If you enjoyed this, leave a comment~