🖼️Docusaurus 从零搭建，面向所有的非技术背景的人，特别适合独立内容生产者，艺术家作品集，小团队。

不要被唬住了！直接扔给AI让它讲，捣鼓完你就有自己的家，加油💪

本文档可以直接阅读，也可以复制全文发给 AI（如 Claude、ChatGPT），让它帮你答疑、排错、生成配置文件。

---

适用人群

• 非技术背景，想有自己的个人站
• 不想学 git、不想碰命令行
• 想脱离平台，自己掌握内容

---

前置准备

具体需要准备什么？

项目	说明	获取方式
Node.js	Docusaurus 运行环境，必须安装 LTS 版本	https://nodejs.org/
VSCode	编辑代码和文档的编辑器	https://code.visualstudio.com/
一个域名	绑定到你的服务器，让别人能访问	阿里云/腾讯云/Namesilo 购买
一台服务器（可选）	部署上线用，初期可以在本地预览	阿里云/腾讯云轻量服务器

安装验证

打开命令提示符（CMD）或 PowerShell，输入：

node --version   # 应显示 v18.x 或更高
npm --version    # 应显示 9.x 或更高

两条命令都正常显示版本号 → 环境准备好了 ✅

---

第一步：安装 Docusaurus

1.1 使用 npx 创建项目

打开命令提示符或 PowerShell，逐条执行：

# 如果网络慢，先切换国内镜像（可选）
npm config set registry https://registry.npmmirror.com

# 创建 Docusaurus 项目（使用经典模板）
npx create-docusaurus@latest my-website classic

# 进入项目目录
cd my-website

# 安装所有依赖
npm install

1.2 本地启动预览

npm run start

浏览器会自动打开 http://localhost:3000，看到 Docusaurus 默认欢迎页即成功 ✅

1.3 停止服务

在命令行窗口按 Ctrl + C，输入 y 确认即可停止。

---

第二步：目录结构

2.1 核心目录结构

my-website/                    # 项目根目录
├── blog/                      # 📝 博客文章存放处
│   └── 2021-08-26-welcome/    # 每篇文章一个文件夹
│       └── index.md           # 文章内容
├── docs/                      # 📚 文档存放处
│   ├── intro.md               # 文档首页
│   └── tutorial-basics/       # 教程分类文件夹
├── src/                       # ⚙️ 源代码
│   ├── components/            # 自定义组件
│   ├── css/                   # 自定义样式
│   └── pages/                 # 独立页面
│       ├── index.js           # ⭐ 首页文件（最重要）
│       └── markdown-page.md   # Markdown 格式的页面
├── static/                    # 🖼️ 静态资源（图片、favicon 等）
│   └── img/                   # 图片文件夹
├── docusaurus.config.js       # ⭐ 站点核心配置（标题、导航栏、页脚等）
├── sidebars.js                # ⭐ 文档侧边栏配置
├── package.json               # 依赖管理
└── README.md                  # 项目说明

2.2 index.js 的作用（首页控制）

src/pages/index.js 是站点的首页入口文件。默认情况下它展示一个漂亮的欢迎页。如果你想直接跳转到文档页面作为首页，可以修改为：

import React from 'react';
import { Redirect } from '@docusaurus/router';

export default function Home() {
  return <Redirect to="/docs/intro" />;
}

2.3 添加一篇新博客文章

在 blog/ 文件夹下创建 我的第一篇文章.md：

---
title: 我的第一篇文章
description: 这是我的第一篇博客
slug: my-first-post
---

欢迎来到我的博客！

这里可以写任何内容，支持 **Markdown** 语法。

## 二级标题

- 列表项 1
- 列表项 2

[这是一个链接](https://docusaurus.io)

2.4 添加一篇新文档

在 docs/ 文件夹下创建 快速开始.md：

---
title: 快速开始
sidebar_position: 1
---

# 快速开始

这是文档的第一页，侧边栏会自动识别这个文件。

## 安装步骤

1. 安装 Node.js
2. 创建项目
3. 启动预览

---

第三步：自动化部署

3.1 构建静态文件

部署前先执行构建，生成纯静态 HTML 文件：

npm run build

构建完成后，所有文件在 build/ 文件夹中。

3.2 创建自动化部署脚本

在项目根目录新建 deploy.bat 文件，内容如下：

@echo off
chcp 65001 >nul
title 🚀 一键部署 Docusaurus

echo.
echo ═══════════════════════════════════════
echo   🚀 开始一键部署流程
echo ═══════════════════════════════════════
echo.

:: ========== 配置区 ==========
set SERVER_IP=你的服务器IP
set SERVER_USER=你的用户名
set SERVER_PORT=22
set SITE_PATH=/你的网站路径/
set ZIP_NAME=build_temp.zip
:: ============================

echo [1/4] 🔨 正在构建网站...
call npm run build
if %errorlevel% neq 0 (
    echo ❌ 构建失败，请检查错误！
    pause
    exit /b %errorlevel%
)
echo ✅ 构建完成！
echo.

echo [2/4] 📦 正在打包 build 文件夹...
powershell -command "Compress-Archive -Path build\* -DestinationPath %ZIP_NAME% -Force"
if %errorlevel% neq 0 (
    echo ❌ 打包失败！
    pause
    exit /b %errorlevel%
)
echo ✅ 打包完成！
echo.

echo [3/4] 📤 正在上传到服务器...
scp -P %SERVER_PORT% %ZIP_NAME% %SERVER_USER%@%SERVER_IP%:/tmp/
if %errorlevel% neq 0 (
    echo ❌ 上传失败！请确认服务器地址和网络连接。
    pause
    exit /b %errorlevel%
)
echo ✅ 上传完成！
echo.

echo [4/4] 📦 服务器端正在解压并部署...
ssh -p %SERVER_PORT% %SERVER_USER%@%SERVER_IP% "unzip -o /tmp/%ZIP_NAME% -d %SITE_PATH% && rm -rf /tmp/%ZIP_NAME%"
if %errorlevel% neq 0 (
    echo ❌ 服务器部署失败！
    pause
    exit /b %errorlevel%
)
echo ✅ 部署完成！
echo.

echo ═══════════════════════════════════════
echo   🎉 部署成功！网站已更新！
echo ═══════════════════════════════════════
echo.

pause

3.3 使用前注意事项

检查项	说明
服务器 IP	替换 你的服务器IP 为实际 IP
服务器目录	替换 你的网站路径 为服务器上网站存放的实际路径
服务器用户名	替换 你的用户名 为实际的 SSH 登录用户名
SSH 连接	首次执行会提示输入服务器密码
服务器需安装 unzip	CentOS: yum install unzip，Ubuntu: apt install unzip

3.4 配置 SSH 免密登录（推荐）

在本地 PowerShell 执行：

# 生成 SSH 密钥（一路回车即可）
ssh-keygen -t rsa

# 上传公钥到服务器（会提示输入密码）
ssh-copy-id root@你的服务器IP

配置成功后，运行 deploy.bat 不再需要输入密码。

---

常见问题（AI 友好版）

编号	问题关键词	一句话描述	解决方法
Q1	端口占用、3000、address already in use	端口 3000 被占用了	npm run start -- --port 3001
Q2	Module not found、安装依赖	依赖包缺失或损坏	rm -rf node_modules && npm install
Q3	配置不生效、修改没反应	修改配置后页面没变化	停止服务（Ctrl+C），重新 npm run start
Q4	图片404、静态资源	图片无法加载	图片放 static/img/，引用用 /img/图片名.png
Q5	部署空白、CSS加载失败	部署后页面是空白	检查 docusaurus.config.js 的 url 和 baseUrl
Q6	scp 失败、permission denied	文件上传被拒绝	检查服务器 IP/用户名/目录权限
Q7	WinRAR 不存在、rar 命令	找不到 WinRAR	安装 WinRAR，或改用 7z 命令
Q8	中文乱码、编码	中文显示乱码	VSCode 用 UTF-8，服务器 export LANG=zh_CN.UTF-8
Q9	修改标题、修改 Logo	更换网站标题和 Logo	编辑 docusaurus.config.js 的 title、favicon
Q10	搜索、Algolia	添加站内搜索	使用 @docusaurus/theme-search-algolia 插件

---

附录：完整配置文件

A. docusaurus.config.js 完整配置

// @ts-check
import { themes as prismThemes } from 'prism-react-renderer';

/** @type {import('@docusaurus/types').Config} */
const config = {
  title: '我的个人站点',
  tagline: '记录思考，分享知识',
  favicon: 'img/favicon.ico',

  // 部署时的正式域名
  url: 'https://你的域名.com',
  // 如果部署在子目录则填写 '/子目录/'
  baseUrl: '/',

  // 可选：GitHub 信息
  organizationName: '你的GitHub名',
  projectName: 'my-website',

  // 链接检查
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',

  // 国际化
  i18n: {
    defaultLocale: 'zh-Hans',
    locales: ['zh-Hans'],
  },

  presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: './sidebars.js',
          editUrl: 'https://github.com/你的GitHub名/my-website/tree/main/',
        },
        blog: {
          showReadingTime: true,
          editUrl: 'https://github.com/你的GitHub名/my-website/tree/main/',
        },
        theme: {
          customCss: './src/css/custom.css',
        },
      }),
    ],
  ],

  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      navbar: {
        title: '我的站点',
        logo: {
          alt: 'Logo',
          src: 'img/logo.svg',
        },
        items: [
          {
            type: 'docSidebar',
            sidebarId: 'tutorialSidebar',
            position: 'left',
            label: '文档',
          },
          { to: '/blog', label: '博客', position: 'left' },
          {
            href: 'https://github.com/你的GitHub名/my-website',
            label: 'GitHub',
            position: 'right',
          },
        ],
      },
      footer: {
        style: 'dark',
        links: [
          {
            title: '文档',
            items: [
              { label: '快速开始', to: '/docs/intro' },
            ],
          },
          {
            title: '更多',
            items: [
              { label: '博客', to: '/blog' },
              { label: 'GitHub', href: 'https://github.com/你的GitHub名/my-website' },
            ],
          },
        ],
        copyright: `Copyright © ${new Date().getFullYear()} 我的站点. Built with Docusaurus.`,
      },
      prism: {
        theme: prismThemes.github,
        darkTheme: prismThemes.dracula,
      },
    }),
};

export default config;

B. sidebars.js 完整配置

/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
  tutorialSidebar: [
    {
      type: 'category',
      label: '入门指南',
      items: [
        'intro',
        '快速开始',
        '安装配置',
      ],
    },
    {
      type: 'category',
      label: '进阶教程',
      items: [
        '进阶/自定义主题',
        '进阶/插件开发',
        '进阶/性能优化',
      ],
    },
    {
      type: 'link',
      label: '官方文档',
      href: 'https://docusaurus.io',
    },
  ],
};

export default sidebars;

C. 快速命令速查

操作	命令
创建项目	npx create-docusaurus@latest my-website classic
安装依赖	npm install
本地预览	npm run start
构建静态文件	npm run build
清理缓存	npm run clear
预览构建产物	npm run serve

---

🚀 有疑问？把这份文档复制给 AI，让它帮你排查和解决！