研究任务: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 原生 TS | astro.config.mjs 由 Node 原生 import() 加载,TLA / process.env / process.argv 全可用;外部 .ts 可用 Node 24 strip-types 直接 import(enum 除外);defineConfig 不支持 async 工厂 | [已验证]/[推测] |
| 3 | updateConfig 的 vite.define | integration 在 astro:config:setup 调 updateConfig({vite:{define,...}}) 会合并进 Vite 配置,对 src/content.config.ts 生效;但只做静态文本替换 | [已验证] |
| 4 | virtual | integration 注册 Vite plugin(Astro 7 无 addVitePlugin),dev/build 均可用;需 env.d.ts 手写类型 | [已验证] |
| 5 | CLI 未知参数 | yargs-parser 静默接受、不报错;--background 子进程只转发白名单 flag,自定义参数会丢 | [已验证] |
| 6 | dev —background | 7.0+ 内置 astro dev --background/stop/status/logs;Windows 不会自动后台,须手动加 flag | [已验证] |
| 7 | site 动态化影响 | 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的写法约束:- 只能用可擦除语法:
interface/type/import type/satisfies/ 普通const;不要enum、namespace、构造器参数属性。 - 类型复用只能
import type(编译/擦除后不产生运行时 import)。若内容仓库不在主题仓库目录内,跨仓库相对路径不稳定 → 推荐「主题导出类型 + 内容仓库复制/生成一份类型声明」或 type-only 引用发布到包(type-researcher 的 task-2 方向)。 - 避免任何运行时 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.tsimport 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-configbuild 后 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-210yargs(argv, { boolean: ['global'], alias: { g: 'global' } }),未知 flag 原样进入flags(yargs-parser 默认不校验);命令解析只看flags._[2]是否在白名单(),未知命令回落 help。 - 实测:
astro build --content fooexit 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 → curlhttp://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.astronew URL(Astro.url.pathname, Astro.site)→<link rel="canonical">、OGog:url、RSS alternate 链接全部随之变化。构建产物已验证(dist/index.html canonical =https://example.com/)。 - @astrojs/sitemap@3.7.4:
if (!config.site)时 warn “The Sitemap integration requires thesiteastro.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 文档)
- 文档:loader 可 “load data from any source, local or remote”(content-loader-reference);
glob()“creates entries from directories of files from anywhere on the filesystem”(同样适用于项目根之外,配合 base);file()读单个 JSON/YAML/TOML;远程内容无内置 loader,需自定义 loader(build-time 拉数据或 live loader),社区 loader 覆盖 Obsidian/GitHub/Bluesky 等(content-collections 指南)。 - 官方没有「内容仓库」这个模式;三种分离层次:
- 同仓库
content/子目录(最简单,项目内路径); - 外部本地目录 +
glob({ base })(本方案); - 远程 CMS + 自定义 loader(本次未采用)。
- 同仓库
- 双仓库约定(根项目已落地):主题仓库持有代码 + schema + 默认 site 配置;内容仓库持有
posts/*.md(mdx)+site.config.ts(可再加package.json提升 Node 加载确定性);通过CONTENT_REPO环境变量切换;schema 始终由主题定义,保证内容仓库内容与主题类型一致。 - 文档出处:https://docs.astro.build/en/reference/content-loader-reference/ ;https://docs.astro.build/en/guides/content-collections/ ;https://docs.astro.build/en/reference/configuration-reference/ ;https://docs.astro.build/en/reference/integrations-reference/ ;https://docs.astro.build/en/reference/cli-reference/ ;https://docs.astro.build/en/guides/upgrade-to/v7/
9. 风险与未验证项
- 跨盘符:
path.relative后仍为绝对路径(内容仓库在另一个盘)时无解,根项目已显式 throw;方案要求同盘(不同目录可以)。 process.cwd()vsconfig.root:根项目src/content.config.ts用process.cwd()解析路径;从其他 cwd 启动(如astro --root、monorepo filter)时可能不一致,更稳的是基于config.root/文件 URL 推导 [风险,未验证]。- dev watch 项目外目录:glob loader 会
watcher.add外部文件,但 Windows 下 chokidar/rolldown watch 项目外目录的可靠性未验证(根项目 dev 两种模式已能跑,未做「改外部 md 热更新」专项测试)。 - 嵌套子项目实验失败:无自身 node_modules 的嵌套最小项目在 sync 时,Vite 8 ModuleRunner 会把根 node_modules 的 CJS
yaml内联执行,报require is not defined(仅astro/loaders触发;flags-test 不 import loaders 故正常)。根项目(自身有 node_modules)不受影响,勿据此判定环境不可用;experiments 结论以根项目实测为准。 - Node TS 语法:内容仓库
site.config.ts不能用 enum/namespace/参数属性;值 import 依赖 Node 解析路径/包,内容仓库没有 node_modules 时失败。 - 虚拟模块类型手写:
src/env.d.ts的 module 声明需与 plugin load 内容保持一致;不同步时astro check可能通过但运行时出错。 - site 变化导致 content store 清空:属预期行为,但频繁切换模式会重复 sync;两种模式的 dist 会互相覆盖(需分 outDir)。
- Windows agent 后台 dev:手动
--background可用,但 detached 子进程可能随 agent Job Object 终止(astro#18019 注释),长驻 dev 需宿主自行管理。 - 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 build8 页、pnpm build --content6 页、CONTENT_REPO=content pnpm build --theme8 页(--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-41transform 后由 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:content8 page(s)(含 /playlist、/theme-layout),pnpm check26 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~