文档站维护

本站用 Docusaurus（一个开源的文档站生成器）构建， 产出纯静态文件，由 Nginx 托管在 docs.187api.com。

为什么用 Docusaurus

• 内容用 Markdown/MDX 写，和写普通文档没区别
• 自带侧边栏、全文搜索、深色模式、版本化
• 构建产物是静态 HTML/CSS/JS，不需要 Node 常驻，Nginx 直接 serve

注意：github.com/meta/docusaurus 是这个框架本身的源码仓库。 给 187API 建站不是去 clone 它，而是用它的发布包 create-docusaurus 生成站点骨架（本项目即如此）。

目录

projects/187api-docs/
├── docusaurus.config.ts   站点配置（标题/域名/导航/页脚）
├── sidebars.ts            侧边栏结构（指南 / API / 进阶）
├── docs/                  所有文档（Markdown）
│   ├── intro.md
│   ├── getting-started/
│   ├── api/
│   ├── advanced/
│   └── reference/
├── src/                   首页与自定义样式
└── static/                图片等静态资源

本地开发

cd projects/187api-docs
npm install           # 首次
npm run start         # 开发服务器，默认 http://localhost:3000

改 docs/ 下任意文件，浏览器自动热更新。

构建

npm run build         # 产物在 build/
npm run serve         # 本地预览构建产物

部署

构建后把 build/ 整个目录同步到服务器静态目录：

npm run build
rsync -avz --delete build/ root@<服务器>:/opt/187api/docs/

Nginx 站点配置（新增一个 server）：

server {
    listen 443 ssl http2;
    server_name docs.187api.com;

    root /opt/187api/docs;
    index index.html;

    location / {
        try_files $uri $uri/ /404.html;
    }

    # 静态资源长缓存
    location ~* \.(js|css|png|jpg|svg|woff2)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}

加一篇文档

1. 在 docs/ 对应目录新建 .md
2. 顶部写 front matter：

   ---
   sidebar_position: 6
   title: 我的新文档
   ---

3. 在 sidebars.ts 里把它的 id（相对 docs/ 的路径）加进对应分类
4. npm run start 预览，确认无误再构建部署

:::warning 改了文档 id / 路径要同步改链接 站内链接写成相对路径（./xxx、../yyy），构建时 onBrokenLinks: 'throw' 会把断链当构建失败——这是故意设的，防止上线死链。 :::

内容来源

API 端点、错误码、缓存/映射规则均对照 projects/new-api 源码写成， 不是凭空编的。改动接口后请同步更新对应文档，避免文档与实现漂移。