备份归档

文档性质：本项目的完整上下文记录，供后续恢复、交接给其他 AI、或自己回顾使用。 最后更新：2026-06-22 项目根目录：E:\AI\zcode\object\Web imitation\

1. 用户信息与偏好

项	内容
操作系统	Windows 11 (10.0.26200 x64)
Shell	cmd.exe（命令行环境为 git-bash 风格）
Node.js 版本	v24.13.1
npm 版本	11.8.0
项目工作目录	`E:\AI\zcode\object\Web imitation\`
桌面用户名	user（桌面路径 `C:\Users\user\Desktop\`）

用户偏好（重要，影响所有交互方式）

版本隔离：所有下载/产物必须留在当前项目目录下，不污染系统环境。
不熟悉命令行：偏好图形界面、双击 bat 文件、记事本式的”傻瓜操作”。
会写基础 Markdown：知道 #、**、- 等基础语法；但不熟悉组件、frontmatter、构建系统。
认知模型：把项目理解为”一个能写文章的网站”，希望像写 TXT 一样写网页内容。
语言：全程中文交流，文档、界面、注释都用中文。
交付风格：喜欢”双击就能用”的东西（bat、快捷方式、记事本打开），不喜欢纯命令行流程。
验证习惯：会实际双击测试，截图反馈问题（截图里能看到浏览器和编辑器实际状态）。

2. 原始需求（用户原话）

需求一：逆向调研 nai4.top

“https://nai4.top/ 查看这个网站，并告诉我它的一个制作途径，还有怎么实现这种网站编辑的效果？用到什么工具啊？这些帮我逆向去调研一下。然后你所有的下载的东西或者这些东西都保留在当前文件夹下、当前项目下，保持版本隔离。“

需求二：询问是否免费

“整个过程是免费的吗？还是有一定的收费标准？“

需求三：克隆技术栈并写文档

“框架 Astro 5 / 主题/UI Starlight / 搜索 Pagefind / 代码块 Expressive Code / 源码托管 GitHub / 部署/CDN Vercel 帮我把这些技术克隆到项目文件夹里，然后针对每一个技术都写一个详细的说明文档。具体要标注清楚这个东西怎么使用，优点是什么？满足了什么样的需求？作者的声明，关于项目的部分，关于项目的介绍”

需求四：学习如何写作

“E:\AI\zcode\object\Web imitation\tool 现在我需要学习一下，就是怎么去用它去写一篇文章，或者写很多文章，写一个大的教程、一个类目。哎，我想要去做这样一种很好看的静态网站形式。我接下来非常具体的操作应该是什么？相关的基础环境，你可以帮我配置到这个目录下。你是以写计划的形式把计划写出来，然后我交给其他AI去执行，因此需要你把计划写得很详细，路径什么的标注清楚”

需求五：像写 TXT 一样写

“我自己怎么像写 TXT 文档那样写这个东西呢？“

需求六：搞清楚在哪儿写、怎么启动

“我是会写基础的 MD 的，嗯，我是不知道在哪儿写，你知道我意思吗？然后这个项目是怎么启动的呀？你写的那个脚本的话，它好像永远指向一个项目，就懂我意思吗？只永远指向一个说明文档”

需求七：归档备份（本次）

“帮我把上面的上下文、之前的调研结果以及给 AI 的提示词等详细内容分类整理，写成 Markdown 格式的文档，留给我做备份，还包括需求啊这些，关于我的部分也记录下来”

3. 调研结果：nai4.top 技术栈逆向

调研方法

纯靠 HTTP 响应头 + HTML 指纹分析，无需服务器访问权限。具体手段：

curl -I 看响应头（Server、X-Powered-By、Via 等）
下载首页和内容页 HTML，分析 DOM 结构、CSS 类名、JS bundle 文件名
对照各框架的已知特征（Astro 的 astro-xxxxx 类名、Starlight 的 sl- 前缀、Pagefind 的 data-pagefind-* 属性等）

nai4.top 实际技术栈

层	技术	证据
框架	Astro 5	HTML 里有 `astro-[hash]` scoped style 类名
主题	Starlight	DOM 结构、`sl-` 类名前缀、内置目录/搜索框布局
搜索	Pagefind	有 `data-pagefind-body`、`data-pagefind-meta` 属性
代码块	Expressive Code	代码块带复制按钮、行高亮、`astro-expressive-code` 容器
托管	GitHub	推测（“Edit on GitHub” 链接指向 GitHub 仓库）
部署	Vercel	响应头 `X-Vercel-Cache`、`X-Vercel-Id`，CDN 全球节点

运作机制（“网站编辑效果”是怎么实现的）

作者在本地用编辑器（Typora/VS Code）写 .md/.mdx 文件
提交到 GitHub 仓库
Vercel 监听到 push，自动拉代码跑 astro build
Astro 把所有 .md 编译成静态 HTML，Pagefind 给 HTML 建搜索索引
Vercel 把 dist/ 部署到全球 CDN
访客打开网址 → 拿到的是纯静态 HTML（快、便宜、SEO 好）

核心特点：写 Markdown 文件 = 更新网站。不需要数据库、不需要后台、不需要服务器常驻。

成本

个人完全免费：

Astro / Starlight / Pagefind / Expressive Code：全部 MIT 开源
GitHub：个人仓库免费
Vercel Hobby 计划：免费（100GB/月带宽，个人用足够）
备选：Cloudflare Pages 同样免费

详细调研报告

完整版见 调研报告.md（项目根目录）。

4. 六大核心技术详解

4.1 Astro 5（核心引擎）

是什么：静态站点生成器（SSG），把组件和 Markdown 编译成纯 HTML
怎么用：npm create astro@latest，或手动建项目（本项目用的手动方式）
优点：零 JS 默认（快）、岛屿架构（按需 hydrate）、支持 MDX/React/Vue/Svelte
满足的需求：让网站又快又轻，SEO 友好
作者：withastro 团队（Fred K. Schott 等创立）
协议：MIT
版本：5.13.7（本项目锁定）
官网：https://astro.build

4.2 Starlight（文档主题）

是什么：Astro 官方文档主题，提供完整的文档站 UI
怎么用：npm i @astrojs/starlight，在 astro.config.mjs 里 integrations: [starlight({...})]
优点：开箱即用——侧边栏、搜索、目录、主题切换、响应式、i18n 全都有
满足的需求：不用自己写 UI，专注内容
作者：Chris Swithinbank（withastro 团队成员）
协议：MIT
版本：0.35.3（本项目锁定）
官网：https://starlight.astro.build

4.3 Pagefind（全文搜索）

是什么：静态站全文搜索引擎，构建时给 HTML 建索引
怎么用：Starlight 自动集成，无需配置。构建后自动跑 pagefind --site dist
优点：零运行时成本（纯静态索引）、中文分词、离线可用
满足的需求：让文档站有专业级搜索（Ctrl+K 唤起）
作者：CloudCannon 团队
协议：MIT
版本：1.5.2（随 Starlight 集成）
官网：https://pagefind.app

4.4 Expressive Code（代码块引擎）

是什么：代码块高亮 + 交互引擎，Shiki 的上层封装
怎么用：Starlight 自动集成。在 Markdown 里写 ```js 即可
优点：复制按钮、行高亮、文件名标签、字面量高亮、明暗双主题
满足的需求：代码示例好看且专业
作者：Tibor Schiemann
协议：MIT
版本：0.41.7（随 Starlight 集成）
官网：https://expressive-code.com

4.5 GitHub（源码托管）

是什么：代码托管平台，本项目用作”源码仓库 + 部署触发器”
怎么用：git init → git remote add origin → git push
优点：免费、版本控制、协作、自动触发 Vercel 部署
满足的需求：存代码 + 触发自动发布
协议：商业服务（个人免费）
官网：https://github.com

4.6 Vercel（部署/CDN）

是什么：静态站/Serverless 部署平台，全球 CDN
怎么用：vercel.com 注册 → 连 GitHub 仓库 → 自动识别 Astro → Deploy
优点：自动构建、全球 CDN、push 即发布、免费额度大
满足的需求：零配置上线 + 全球加速
协议：商业服务（Hobby 计划免费）
官网：https://vercel.com

5. 项目结构与产物清单

5.1 顶层目录

E:\AI\zcode\object\Web imitation\
├─ 调研报告.md              ← 完整逆向调研报告（早期产物）
├─ 项目档案与备份.md        ← 本文档（备份用）
├─ nai4_home.html           ← nai4.top 首页快照（调研素材）
├─ content_page.html        ← nai4.top 内容页快照（调研素材）
├─ nai4-clone\              ← 克隆项目（演示用，含六技术文档）
└─ tool\                    ← ★ 写作模板（用户实际在用的）★

5.2 `nai4-clone\` — 技术栈克隆演示项目

用途：复刻 nai4.top 的技术栈，并为六项技术各写一篇详细说明文档。状态：已完成，9 页全部构建通过。

nai4-clone\
├─ package.json             ← astro@^5.13.7, @astrojs/starlight@^0.35.3
├─ astro.config.mjs         ← sidebar autogenerate directory: '.'
├─ tsconfig.json
├─ .gitignore
├─ README.md
└─ src\
   ├─ content.config.ts     ← 显式 docsLoader() + docsSchema()
   └─ content\docs\
      ├─ index.mdx          ← 首页（含技术卡片网格）
      ├─ astro.mdx          ← Astro 5 详细文档
      ├─ starlight.mdx      ← Starlight 详细文档
      ├─ pagefind.mdx       ← Pagefind 详细文档
      ├─ expressive-code.mdx ← Expressive Code 详细文档（修复过 MDX 解析错误）
      ├─ github.mdx         ← GitHub 详细文档
      ├─ vercel.mdx         ← Vercel 详细文档
      └─ about-project.mdx  ← 项目总览页

5.3 `tool\` — 写作模板（用户实际使用）

用途：纯净的写作环境，用户在这里写文章/教程/类目。状态：已完成，可运行，9 页构建通过。

tool\
├─ package.json             ← name: my-docs-site
├─ astro.config.mjs         ← 中文界面 + 4 个侧边栏分组（文章/入门/进阶教程/其它）
├─ tsconfig.json
├─ .gitignore
├─ new-post.cjs             ← 新建文章脚本（弹窗问标题，默认建到 posts/）
├─ 新建文章.bat             ← 双击：调 new-post.cjs
├─ 开始写作.bat             ← 双击：开 dev 服务器 + 浏览器
├─ 极简写作说明.txt         ← 给用户看的傻瓜说明
├─ 写作指南.md              ← 给 AI 看的详细规则（11 节）
├─ public\
│  └─ favicon.svg           ← 默认站点图标（紫色 D 字）
└─ src\
   ├─ content.config.ts     ← Content Layer API 集合声明
   ├─ assets\               ← 放图片（被文章 import 引用）
   └─ content\docs\
      ├─ index.mdx          ← 首页（splash 模板 + Hero 按钮 + 卡片）
      ├─ about.mdx          ← 关于本站
      ├─ posts\             ← ★ 默认文章分组 ★
      │  ├─ 20260622-005107.md   ← 用户测试写的（内容："萨达"）
      │  ├─ 20260622-012551.md
      │  └─ 20260622-014724.md
      ├─ getting-started\   ← "入门" 类目示例
      │  ├─ intro.mdx       ← 写作入门
      │  └─ organize.mdx    ← 怎么组织教程/类目
      └─ guide\             ← "进阶教程" 类目示例
         ├─ lesson-1.mdx    ← 演示 Aside/提示框
         └─ lesson-2.mdx    ← 演示 Steps/表格/图片

5.4 桌面快捷方式

C:\Users\user\Desktop\my-docs.lnk → 指向 tool\src\content\docs\（用户写作文件夹）

6. 踩坑记录与解决方案

这部分是最值钱的工程知识，后续 AI 必读，否则会重蹈覆辙。

坑 1：GitHub codeload 不可达，无法用模板创建项目

症状：npm create astro@latest --template starlight 卡死/超时
原因：网络问题，GitHub codeload 在用户网络下访问不稳定
解决：手动创建项目结构 + npm install --registry=https://registry.npmmirror.com（国内镜像，19 秒装完）

坑 2：Astro 5 自动集合已废弃警告

症状：构建报警告 “Auto-generated collections are deprecated”
原因：Astro 5.18+ 要求用 Content Layer API 显式声明集合

解决：新建 src/content.config.ts：

import { defineCollection } from 'astro:content';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';
const docs = defineCollection({ loader: docsLoader(), schema: docsSchema() });
export const collections = { docs };

坑 3：sidebar autogenerate 找不到文件

症状：autogenerate: { directory: 'docs' } 侧边栏空
原因：directory 是相对于 src/content/docs/ 的，写 'docs' 会去找 src/content/docs/docs/
解决：改成 directory: '.'（整站）或具体子目录名如 'posts'

坑 4：构建只生成 1 页（404），dev 正常 ★最坑★

症状：astro build 只输出 /404.html，所有文章都没编译
排查过程（错误方向）：怀疑 Node 版本、Astro 版本、tsconfig——都不是
真正原因：某个 .mdx 文件里，<Card> JSX 组件内部写了裸 ``` 代码块和 {大括号}。MDX 解析器把这些当 JSX 表达式，找不到闭合标签，整个 build 静默失败（404 在错误发生前已写入，所以看起来”只生成 1 页”）
解决：把代码示例移到 JSX 组件外面；组件内部只放纯文字
铁律：任何在 <组件>...</组件> 之间的内容，不要写代码块或裸 {

坑 5：首页链接 404

症状：首页两个 Hero 按钮 + 三处链接点击全是 404
原因：链接写成 /docs/astro/，但 Starlight 路由规则里集合名 docs 不出现在 URL 里
正确规则：
- src/content/docs/astro.mdx → URL /astro/（不是 /docs/astro/）
- src/content/docs/guide/lesson-1.mdx → URL /guide/lesson-1/
- 链接永远末尾带 /，永远不带 .md 后缀

坑 6：Starlight 0.35 没有 Note/Tip/Warning/Caution 组件

症状：import { Note } from '@astrojs/starlight/components' 报 “is not exported”
原因：Starlight 0.35 的 user-components 只导出这些： Aside, Badge, Card, CardGrid, Icon, Tabs, TabItem, LinkCard, LinkButton, Steps, FileTree, Code
解决：用 GitHub aside 语法代替（推荐）：
```
> [!NOTE]
> 内容
> [!TIP] / [!WARNING] / [!CAUTION]
```
或用 <Aside type="note"> 组件

坑 7：`<Steps>` 组件语法

症状：报 “expects a single ordered list (<ol>) but found multiple child elements”
原因：Steps 内部用了 ### 标题

解决：Steps 内部必须用有序列表：

<Steps>
  1. **第一步**

     说明（缩进 4 空格）。
  2. **第二步**
     说明。
</Steps>

坑 8：脚本 `require is not defined`

症状：node new-post.js 报 ReferenceError
原因：package.json 设了 "type": "module"，所有 .js 被当 ES module，不能用 require
解决：脚本改后缀为 .cjs

坑 9：PowerShell 脚本中文乱码

症状：.ps1 文件里的中文被当 GBK 解析，报”字符串缺少终止符”
解决：.ps1 文件里不写中文，或保存为 UTF-8 BOM 编码

坑 10：散放文章不进侧边栏（用户反馈的”没看到修改”问题）

症状：用户在 docs\ 根目录建了 .md，浏览器看侧边栏没有
原因：sidebar 只 autogenerate 了 getting-started/ 和 guide/，根目录散放文件无人收
解决：新建 posts/ 文件夹 + sidebar 加 { label: '文章', autogenerate: { directory: 'posts' } } + 脚本默认建到 posts/

坑 11：dev 服务器改了 config 不生效

症状：改 astro.config.mjs 后浏览器没变化
原因：dev 服务器对 config 变更不热刷新
解决：Ctrl+C 关掉 dev → 重新 npm run dev

7. 给后续 AI 的提示词模板

7.1 让 AI 帮忙写文章（最常用）

我要在我的文档站写一篇文章。

项目路径：E:\AI\zcode\object\Web imitation\tool\
文章存放位置：src\content\docs\posts\（默认）或指定子文件夹
文章格式：.md 文件，开头必须有 frontmatter：
  ---
  title: 文章标题
  ---

请帮我写一篇关于【主题】的文章，要求：
1. 文件名用英文或时间戳（避免中文 URL 乱码）
2. 标题用中文
3. 用基础 Markdown 语法（# ## **加粗** - 列表 [链接](url)）
4. 代码块用三反引号
5. 不要用 Starlight 不支持的组件（Note/Tip/Warning/Caution 都没有，
   用 > [!NOTE] 语法代替）
6. 写完告诉我文件路径，我自己 Ctrl+S 保存看效果

写完直接放到 src\content\docs\posts\ 下，文件名用【主题英文】.md

7.2 让 AI 帮忙开新教程类目

我要在我的文档站开一个新教程类目：【类目名，如 Python 入门】

项目路径：E:\AI\zcode\object\Web imitation\tool\

请按这个 SOP 操作（参考 写作指南.md 第 10 节）：
1. 建文件夹：src\content\docs\【类目英文名】\
2. 在 astro.config.mjs 的 sidebar 数组末尾加：
     {
       label: '【类目中文名】',
       autogenerate: { directory: '【类目英文名】' },
     },
   （注意上一条末尾要有逗号）
3. 在新文件夹下建 N 个 .mdx 文件，每个 frontmatter 带 sidebar.order 排序
4. 文章间互相链接用 /【类目英文名】/【文件名】/ 格式
5. 改完 config 必须重启 dev（Ctrl+C 后 npm run dev）
6. 跑 npm run build 验证无报错

红线（违反就报错）：
- 不要在 <组件>...</组件> 之间写代码块或裸 {
- 不要 import Starlight 不导出的组件
- 链接永远末尾带 /，不带 /docs/ 前缀，不带 .md 后缀
- 文件名用英文/拼音，title 用中文

7.3 让 AI 接手维护这个项目（完整交接）

你正在接手一个 Astro + Starlight 文档站项目。

【背景】
- 这是 nai4.top 技术栈的克隆，目的是让用户像写 TXT 一样写网站文章
- 用户不熟悉命令行，偏好图形界面、双击 bat、记事本式操作
- 用户会写基础 Markdown，但不懂组件/frontmatter/构建系统

【必读文档】（按顺序读）
1. E:\AI\zcode\object\Web imitation\项目档案与备份.md ← 完整上下文（本文档）
2. E:\AI\zcode\object\Web imitation\tool\写作指南.md   ← 11 节详细规则
3. E:\AI\zcode\object\Web imitation\tool\极简写作说明.txt ← 用户视角说明

【关键路径】
- 项目根：E:\AI\zcode\object\Web imitation\tool\
- 文章目录：tool\src\content\docs\
- 配置文件：tool\astro.config.mjs
- 新建脚本：tool\new-post.cjs（默认建到 posts\）
- 启动脚本：tool\开始写作.bat（双击开 dev+浏览器）

【铁律】
- 所有改动留在项目目录内，版本隔离
- 中文交流，中文文档，中文界面
- 交付"双击就能用"的东西，不要纯命令行流程
- 改 config 后提醒用户重启 dev
- 永远先 npm run build 验证再交付

【当前状态】
- 9 页全部构建通过，dev 可跑
- 用户刚学会用 新建文章.bat 写文章（已写过测试篇"萨达"）
- posts\ 分组已配置好，新文章默认进这里

7.4 让 AI 部署上线

帮我把 E:\AI\zcode\object\Web imitation\tool\ 部署到公网。

推荐方案：Vercel（免费、全球 CDN、自动识别 Astro）

步骤（用户操作，AI 指导）：
1. 在 tool\ 目录初始化 git：
     cd tool
     git init
     git add .
     git commit -m "initial"
2. 在 GitHub 建一个新仓库（public 或 private 都行）
3. 关联远程并推送：
     git remote add origin https://github.com/【用户名】/【仓库名】.git
     git branch -M main
     git push -u origin main
4. 去 https://vercel.com 用 GitHub 一键登录
5. New Project → 选刚才的仓库 → 自动识别 Astro → Deploy
6. 等 1 分钟，拿到 https://【仓库名】.vercel.app
7. （可选）Settings → Domains 绑定自定义域名

以后只要 git push，Vercel 自动重新构建发布。

注意：
- .gitignore 已排除 node_modules\ 和 dist\，不会传上去
- 部署前先把 astro.config.mjs 的 site 改成正式域名

8. 当前状态与下一步

8.1 已完成 ✅

8.2 待用户决定 / 可选下一步

部署上线：把 tool\ 推到 GitHub + Vercel（见 7.4 节提示词）
换编辑器：从记事本升级到 Typora（所见即所得）或 VS Code（带预览）
写正式内容：删掉 posts\ 下的测试文章，开始写真教程
自定义外观：换 favicon、换站点标题、调主题色
加自定义组件：如果想加评论、统计、广告位等

8.3 联系点 / 验证清单

交付给用户后，让用户做这 4 步验证整套东西能跑：

双击桌面 my-docs → 进到 docs 文件夹
双击 tool\开始写作.bat → 浏览器开起来
用记事本打开 posts\ 下任一 .md，改两个字，Ctrl+S
看浏览器——0.1 秒自动刷新

走通这 4 步 = 整套系统正常工作。

附：关键命令速查

操作	命令/动作
启动写作环境	双击 `tool\开始写作.bat`
新建文章	双击 `tool\新建文章.bat`（默认进 posts\）
进文章文件夹	双击桌面 `my-docs` 快捷方式
手动构建	`cd tool && npm run build`
预览构建产物	`cd tool && npm run preview`
重启 dev（改 config 后）	关黑窗口 → 重新双击 `开始写作.bat`
装依赖（换电脑时）	`cd tool && npm install --registry=https://registry.npmmirror.com`

文档结束。把这份文档 + tool\写作指南.md + tool\极简写作说明.txt 三份给任何 AI，它就能完整接手这个项目。