搭建指南

本页详细记录了当前这个站点的完整搭建过程：环境检查 → 初始化 → docs-only 配置 → TypeScript 类型检查 → 构建启动 → 访问验证。可作为复现或排查问题时的参考手册。

快速结论

环境就绪后，下面几步即可搭起和本站一致的结构（TypeScript + docs-only）。然后浏览器打开 http://localhost:3000/，根路径直接显示文档。

npx create-docusaurus@latest . classic --typescript   # 1. init (TS template)
npm run build                                         # 2. build check
npm run start                                         # 3. start dev server

---

1. 前置环境检查

Docusaurus 需要 Node.js 18 及以上（本项目实测 v24.7.0，npm 11.5.1）。开始前确认：

node -v          # expect v18+; this project uses v24.7.0
npm -v           # should be available
npm ping         # verify registry access; PONG = ok

# Check port 3000 is free (default dev server port)
ss -tlnp | grep ':3000' || echo '3000 free'

没有 Node.js？

推荐使用 nvm 安装并管理 Node 版本：

nvm install --lts
nvm use --lts

---

2. 初始化项目（TypeScript 模板）

目标目录为空时，可直接在当前目录初始化（用 . 作为路径）：

npx create-docusaurus@latest . classic --typescript

• classic 模板内置 docs + blog + 预设页面，最适合作为起点。
• --typescript 直接生成 .ts/.tsx 配置与组件，并预置 tsconfig.json。
• 脚手架会自动执行 npm install，生成 docusaurus.config.ts、sidebars.ts、docs/、blog/、src/、static/ 等。
• 本项目初始化得到的版本为 create-docusaurus@3.10.1。

⚠️ 关于交互式提示

脚手架会询问使用的语言（JavaScript / TypeScript）。若已加 --typescript 则跳过该问。

• 在真实终端中用方向键选择即可。

• 若在脚本/非交互环境（例如通过管道运行），需主动喂入答案，否则会卡住：

  printf '\n' | npx create-docusaurus@latest . classic --typescript   # pick default non-interactively

备注

本站使用的是 TypeScript 配置。

---

3. 配置 docs-only 模式（根路径直接显示文档）

本站移除了独立首页，访问根路径 / 时直接显示第一篇文档，地址栏保持 /。这是 Docusaurus 的 docs-only 模式，需三处改动：

1. 在 docusaurus.config.ts 的 docs 预设里加 routeBasePath: '/'：

   presets: [
     [
       'classic',
       {
         docs: {
           routeBasePath: '/',     // docs served at root path
           sidebarPath: './sidebars.ts',
         },
         blog: { /* ... */ },
       },
     ],
   ],

2. 删除 src/pages/index.tsx（否则 / 路由与文档首页冲突）。

3. 给作为首页的文档加 slug: /（本站是 docs/getting-started.mdx）：

   ---
   sidebar_position: 0.5
   slug: /
   ---

URL 会变

docs-only 模式下，所有文档 URL 从 /docs/xxx 变为 /xxx（例如 /docs/intro → /intro）。页脚、导航里若有 /docs/... 绝对链接需同步更新，否则 onBrokenLinks: 'throw' 会让构建失败。

---

4. TypeScript 类型检查

docusaurus build / start 用 SWC 转译 TS，不做类型检查；类型错误需单独跑：

npm run typecheck

两个坑（来自实测）

1. TypeScript 版本冲突：create-docusaurus 在某些环境会装到 typescript@7.x，而 @docusaurus/tsconfig 预设仍使用 baseUrl——TS 7 已移除该选项，会报 TS5102。解法是降到 5.x：

   npm install --save-dev typescript@5

2. tsconfig 的 baseUrl 必须显式声明：extends 时，预设里的 paths（@site/*）相对预设文件位置解析，会导致 @site/... 别名全部找不到模块。子配置必须显式写 baseUrl: "." 锚定到项目根（这也是官方 TS 模板的标准写法）：

   {
     "extends": "@docusaurus/tsconfig",
     "compilerOptions": {"baseUrl": "."},
     "include": ["src/", "docusaurus.config.ts", "sidebars.ts"]
   }

Admonition 语法

写 :::tip / :::note 提示框时，:::type 必须独占一行、其后留空行，标题用 :::type[标题]。否则整段会被当普通文本，页面上出现字面的 :::。

---

5. 构建与启动

npm run build      # production build, outputs to build/
npm run start      # dev server (hot reload), default http://localhost:3000/

构建成功时：

[INFO] [en] Creating an optimized production build...
[SUCCESS] Generated static files in "build".

• 开发服务器支持热更新：修改 docs/ 下的 markdown 或组件，浏览器自动刷新。
• 改 docusaurus.config.ts 不会热更新，需手动重启 npm run start。
• 这是长驻进程，需后台运行或单独保留终端。

局域网访问（可选）

npm run start -- --host 0.0.0.0

---

6. 访问验证（docs-only 路由）

服务器就绪后验证关键路由：

curl -sS -o /dev/null -w '%{http_code}\n' http://localhost:3000/        # root → 200 (home doc)
curl -sS -o /dev/null -w '%{http_code}\n' http://localhost:3000/intro   # doc → 200
# /blog is disabled and returns Page Not Found

浏览器打开 http://localhost:3000/，直接看到文档内容即说明整条链路打通。

---

7. 常用命令速查

命令	用途	说明
npm run start	开发服务器	热更新，日常写作首选
npm run build	生产构建	输出到 build/
npm run serve	预览构建产物	本地起服务访问 build/
npm run typecheck	TypeScript 类型检查	build 不含类型检查，需单独跑
npm run clear	清理缓存	出现莫名构建问题时先试它
npm run deploy	部署	默认部署到 GitHub Pages

---

8. 目录结构

docusaurus-demo/
├── blog/                  # blog posts (markdown/mdx; disabled for now)
├── docs/                  # docs (this page lives here)
│   ├── getting-started.mdx   # slug: / → site home doc
│   ├── intro.mdx
│   ├── tutorial-basics/
│   └── tutorial-extras/
├── src/                   # custom pages, components, styles
│   ├── components/        # HomepageFeatures etc. (unused under docs-only, kept)
│   ├── css/
│   └── pages/
├── static/                # static assets (images), copied as-is
├── docusaurus.config.ts   # global config (title, URL, theme, docs-only, etc.)
├── sidebars.ts            # sidebar config (autogenerated)
├── tsconfig.json          # TypeScript config
├── package.json
└── README.md

添加新文档

侧边栏由 sidebars.ts 中的 {type: 'autogenerated', dirName: '.'} 按文件夹结构自动生成，只需在 docs/ 下新建 .md/.mdx 并设 frontmatter：

---
sidebar_position: 2
---

# 我的新文档

正文内容……

无需手动改 sidebars.ts，新页面自动出现在侧边栏。

---

9. 常见问题

端口 3000 被占用

换一个端口启动：

npm run start -- --port 3001

构建出现诡异错误

清理缓存重来：

npm run clear
npm run build

改了配置不生效

docusaurus.config.ts 改完后需手动重启 npm run start（配置不热更新）。

构建报「broken link / 找不到模块」

onBrokenLinks: 'throw' 会让任何死链直接失败。docs-only 模式后记得把页内 /docs/xxx 链接改成 /xxx。