当前位置：首页 > news >正文

【官网开发】Docusaurus 建站初探-TypeScript 版-1

news 2025/9/14 6:14:39

一图胜千言

在这里插入图片描述
这个网站是开源的蛤：开源地址是：https://gitee.com/lcmac/smart-api-website

Docusaurus官网地址：

https://www.docusaurus.cn/docs

下面给出一条「从零到上线」的完整链路，照着敲即可在 30 分钟内把 Docusaurus 站点跑起来并发布到公网。所有命令均在 2025-07 以后验证有效。

一、前置准备（2 min）

Node.js ≥ 18
```
node -v      # 建议 18.x 或 20.x
```
Git 已安装并配置好用户名 / 邮箱（后面部署用）

二、创建项目（3 min）

# 使用官方脚手架，classic 主题 + TypeScript 支持
npx create-docusaurus@latest my-website classic --typescript
cd my-website
npm install               # 若自动装过可跳过
npm run start             # 本地开发服务器 → http://localhost:3000

目录结构一览：

my-website
├── blog/                 # 博客 Markdown
├── docs/                 # 文档 Markdown
├── src/                  # 自定义页面 / 组件
├── static/               # 纯静态文件（favicon、CNAME …）
├── docusaurus.config.js  # 核心配置
└── package.json

三、常见个性化修改（10 min）

改基本信息 – docusaurus.config.js

title: '我的知识库',
tagline: '记录 & 分享',
url: 'https://your-name.github.io',   // 无尾斜杠
baseUrl: '/my-website/',             // 仓库名
organizationName: 'your-name',       // GitHub 用户名
projectName: 'my-website',           // 仓库名

导航栏 / 页脚 – 同文件内 themeConfig 节点，按需增删菜单。
首页 – 修改 src/pages/index.tsx 或整页替换。
侧边栏 – sidebars.ts 控制文档层级；新建 .md 后在此注册。
多语言 – 在 i18n 目录新增 zh-Hans 等，配置 i18n 节点即可。

四、本地构建与预览（2 min）

npm run build        # 生成静态文件到 build/ 目录
npm run serve        # 本地 3000 端口预览生产包

若后续出现缓存怪病：

npm run clear        # 一键删缓存 + build

五、部署到 GitHub Pages（5 min 配完，push 自动发布）

把项目推到 GitHub（公开 / 私有均可）

git remote add origin git@github.com:your-name/my-website.git
git push -u origin main

生成 GitHub Actions 工作流（Docusaurus 已内置）

# 一条命令生成 deploy.yml & test-deploy.yml
npx docusaurus github-actions

或手动放 .github/workflows/deploy.yml：

name: Deploy to GitHub Pages
on:push:branches: [ main ]
jobs:build:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v4- uses: actions/setup-node@v4with:node-version: 18cache: npm- run: npm ci- run: npm run build- uses: actions/upload-pages-artifact@v3with:path: builddeploy:needs: buildpermissions:pages: writeid-token: writeenvironment:name: github-pagesurl: ${{ steps.deployment.outputs.page_url }}runs-on: ubuntu-lateststeps:- uses: actions/deploy-pages@v4

开启 Pages 服务
GitHub 仓库 → Settings → Pages → Source 选 GitHub Actions → Save。
以后每次 push 到 main 即自动构建并发布到
https://your-name.github.io/my-website/

六、其它托管一键方案（可选）

平台	构建命令	发布目录	特殊配置
Vercel	`npm run build`	`build`	默认即可
Netlify	`npm run build`	`build`	无需额外文件
自建服务器 / Nginx	`npm run build` 后把 `build/` 目录丢到 `/var/www/html`	见的 Nginx 配置示例

七、常用 CLI 速查

npm start                # 开发服务器
npm run build           # 生产构建
npm run serve           # 本地预览生产包
npm run deploy          # 直接 push 到 gh-pages 分支（旧方案）
npx docusaurus swizzle  # 弹出主题组件做深度定制
npx docusaurus clear    # 清缓存