云信AI部署

Docusaurus完全指南：从安装到高级应用（Windows 11环境）

云信安装大师
90
AI 质量分
10 5 月, 2025
7 分钟阅读
0 阅读

Docusaurus完全指南：从安装到高级应用（Windows 11环境）

引言

Docusaurus 是 Facebook 开源的一款现代化的静态网站生成器，特别适合构建文档网站、博客和技术文档。它基于 React 构建，提供了开箱即用的优秀功能，如文档版本控制、国际化支持等。本文将带你在 Windows 11 环境下从零开始安装 Docusaurus，并介绍一些高级应用技巧。

准备工作

在开始之前，请确保你的 Windows 11 系统满足以下要求：

  1. Node.js v16.14 或更高版本
  2. Yarn v1.22+（推荐）或 npm v6+
  3. Git（用于版本控制）
  4. VSCode（或其他代码编辑器）

第一步：安装 Node.js

  1. 访问 Node.js 官网
  2. 下载 LTS 版本（当前为 v18.x）
  3. 运行安装程序，保持默认设置
  4. 安装完成后验证安装：
代码片段 
node -v
npm -v

第二步：创建 Docusaurus 项目

打开 PowerShell（管理员权限不是必需的）：

代码片段 
npx create-docusaurus@latest my-website classic

参数说明：
– my-website：你的项目文件夹名称
– classic：使用经典模板（包含文档和博客功能）

如果你想创建一个更简洁的项目：

代码片段 
npx create-docusaurus@latest my-website basic

第三步：启动开发服务器

进入项目目录并启动开发服务器：

代码片段 
cd my-website
npm run start

这将在 http://localhost:3000 启动一个热重载的开发服务器。

项目结构解析

了解项目结构对于后续开发很重要：

代码片段 
my-website/
├── blog/                # Markdown格式的博客文章
├── docs/                # Markdown格式的文档
├── src/
│   ├── css/             # 自定义CSS样式
│   ├── pages/           # React页面组件
│   └── components/      # React组件
├── static/              # 静态资源文件（图片等）
├── docusaurus.config.js # Docusaurus主配置文件
└── package.json         # Node.js项目配置和依赖管理

第四步：添加新文档

  1. 在 docs 文件夹中创建新的 Markdown 文件，例如 getting-started.md
  2. 添加必要的元数据（front matter）：
代码片段 
---
title: Getting Started
description: This is my first document in Docusaurus.
---

# Getting Started

Welcome to my documentation!

Here's how to get started...

[Learn more about Markdown](https://commonmark.org/help/)
  1. Docusaurus会自动检测新文档并在侧边栏显示

第五步：自定义侧边栏

编辑 sidebars.js：

代码片段 
module.exports = {
  tutorialSidebar: [
    {
      type: 'category',
      label: 'Getting Started',
      items: ['getting-started'],
    },
    {
      type: 'category',
      label: 'Advanced',
      items: ['advanced-configuration'],
    },
    {
      type: 'doc',
      id: 'api-reference',
    },
    {
      type: 'link',
      label: 'GitHub',
      href: 'https://github.com/your-repo',
    },
],
};

第六步：添加博客文章

  1. 在 blog 文件夹中创建新的 Markdown 文件，例如 2023-01-01-welcome.md
  2. Front matter示例：
代码片段 
---
title: Welcome to My Blog!
author: Your Name 
tags: [welcome, introduction]
---

This is my first blog post on Docusaurus!

More content here...

Docusaurus配置详解

编辑 docusaurus.config.js：

代码片段 
module.exports = {
 title: 'My Site', // Title for your website.
 tagline: 'The tagline of my site',
 url: 'https://your-site.com', // Your website URL 
 baseUrl: '/', // Base URL for your project */
 favicon: 'img/favicon.ico',

 organizationName: 'facebook', // Usually your GitHub org/user name.
 projectName: 'docusaurus', // Usually your repo name.

 themeConfig: {
   navbar: {
     title: 'My Site',
     logo: {
       alt: 'My Site Logo',
       src: 'img/logo.svg',
     },
     items: [
       {to: 'docs/getting-started', label: 'Docs', position: 'left'},
       {to:'blog', label:'Blog', position:'left'},
       {
         href:'https://github.com/facebook/docusaurus',
         label:'GitHub',
         position:'right',
       },
     ],
   },
   footer:{
     style:'dark',
     links:[ /* ... */ ],
     copyright:`Copyright © ${new Date().getFullYear()} My Project, Inc.`,
   },
 },

 presets:[ /* ... */ ],
};

SEO优化技巧

  1. 添加meta标签：

“`javascript {5-10}
// docusaurus.config.js
themeConfig:{
metadata:[
{name:’keywords’, content:’documentation, blog, react’},
{name:’description’, content:’My awesome documentation site’},
{name:’og.description’, content:’My awesome documentation site’},
],
},

代码片段 

2. **创建sitemap**：

在配置文件中启用插件：

```javascript {5}
// docusaurus.config.js
plugins:[ 
 '@docusaurus/plugin-sitemap',
],
  1. Google Analytics集成：

“`javascript {5-9}
// docusaurus.config.js
themeConfig:{
googleAnalytics:{
trackingID:’UA-XXXXX-Y’,
anonymizeIP:true,
},
},

代码片段 

## Windows环境常见问题解决

### npm install失败问题

如果遇到权限问题，可以尝试：

npm cache clean --force && npm install --global windows-build-tools --vs2015 && npm install --global node-gyp && npm install --no-optional --force && npm rebuild node-sass --force && npm install --force && npm start || yarn start || yarn dev || yarn develop || yarn build || yarn serve || yarn start"

EMFILE错误（文件打开过多）

在PowerShell中运行：

代码片段 
set NODE_OPTIONS=--max-old-space-size=4096 && set UV_THREADPOOL_SIZE=4 && set NODE_NO_WARNINGS=1 && set NODE_ENV=development && set DEBUG=docusaurus:* && set FORCE_COLOR=true && set CI=true && set GIT_SSL_NO_VERIFY=true && set ELECTRON_RUN_AS_NODE=1 && set OPENSSL_CONF=C:\dev\openssl.cnf && set HOMEDRIVE=C:

Git Bash中的路径问题

如果你使用Git Bash而不是PowerShell，可能会遇到路径问题。解决方案是添加以下别名到你的 .bashrc：

代码片段 
alias npm='npm.cmd'
alias npx='npx.cmd'
alias yarn='yarn.cmd'

Docker部署方案

如果你希望使用Docker来部署Docusaurus站点：

  1. 创建Dockerfile:
代码片段 
FROM node:16-alpine AS builder

WORKDIR /app

COPY package.json yarn.lock ./

RUN yarn install --frozen-lockfile

COPY . .

RUN yarn build


FROM nginxinc/nginx-unprivileged AS production 

COPY --from=builder /app/build /usr/share/nginx/html 

COPY nginx.conf /etc/nginx/conf.d/default.conf 

EXPOSE $PORT 

CMD ["nginx", "-g", "daemon off;"]
  1. nginx.conf:
代码片段 
server {
 listen $PORT;
 server_name localhost;
 root /usr/share/nginx/html;
 index index.html;

 location / {
   try_files $uri $uri.html $uri/index.html =404;
 }
}
  1. 构建和运行:
代码片段 
docker build -t docusaurus-site .
docker run -p3000:$PORT -e PORT=3000 docusaurus-site

GitHub Pages自动部署

  1. 创建部署脚本 (deploy.sh):
代码片段 
#!/bin/bash 

echo "Deploying updates to GitHub..."

# Build the project.
npm run build 

# Go To Build folder 
cd build 

# Add changes to git.
git init 
git add -A 

# Commit changes.
msg="rebuilding site `date`"
if [ $# -eq1 ]
 then msg="$1"
fi 
git commit -m "$msg"

# Push source and build repos.
git push -f git@github.com:<USERNAME>/<REPO>.git master:<TARGET-BRANCH>

cd ..
  1. 设置GitHub Actions工作流 (.github/workflows/deploy.yml):
代码片段 
name:Docs Deployment 

on:
 push:
 branches:
   - main 

jobs:
 deploy:
 runs-on:${{ matrix.os }}
 strategy:
 matrix:
 os:[ubuntu-latest]

 steps:
 - uses:${{ github.action }}/checkout@v2

 - name:${{ github.node }}
 uses:${{ github.action }}/setup-node@v2

 with:
 node-version:${{ github.node }}
 cache:${{ github.yarn }}

 - run:npm ci 

 - run:npm run build 

 - name:${{ github.pages }}
 uses:${{ github.action }}/gh-pages@v3

 with:
 github_token:${{ secrets.GITHUB_TOKEN }}
 publish_dir:/build/
  1. 推送更改后自动部署

每次推送到main分支时，GitHub Actions会自动构建并部署你的站点。

Vercel一键部署方案

如果你更喜欢使用Vercel:

  1. 导入你的Docusaurus仓库
  2. 选择框架预设为”Other”
  3. 构建命令设置为: npm run build
  4. 输出目录设置为: build
  5. 环境变量不需要特殊设置
  6. 点击”Deploy”

Vercel会自动处理路由重写和HTTPS证书。

Algolia搜索集成(高级)

让你的文档拥有强大的搜索功能:

1.注册Algolia账户
2.创建DocSearch应用

修改docusaurus.config.js:

“`javascript {5-12}
themeConfig:{
algolia:{
appId:”YOURAPPID”,
apiKey:”YOURSEARCHAPIKEY”,
indexName:”YOURINDEX_NAME”,
contextualSearch:”true”,
searchParameters:{},
searchPagePath:”search”,
},
},

代码片段 

然后添加CSS样式到`src/css/custom.css`:

```css 
.DocSearch-Modal .DocSearch-Hit a{
 box-shadow:none!important;
}

.DocSearch-Button{
 margin-left:.5rem!important;
 border-radius:.25rem!important;
}

## i18n国际化支持(高级)

Docusaurus内置了国际化支持:

1.启用i18n功能

修改docusaurus.config.js:

“`javascript {5-15}
i18n:{
defaultLocale:”en”,
locales:[ “en”,”zh”,”ja”,”fr”],
localeConfigs:{
en:{
htmlLang:”en-US”,
},
zh:{
htmlLang:”zh-CN”,
},
},
},

代码片段 

2.**翻译你的内容**

运行以下命令生成翻译文件结构:

 ```bash 
npm run write-translations -- --locale zh

这会生成一个包含所有可翻译字符串的JSON文件。

3.翻译Markdown内容

将你的Markdown文件复制到对应的语言目录下并翻译内容:

代码片段 
docs/
 ├── getting-started.md        # English version  
 └── i18n/
     └── zh/
         └── getting-started.md # Chinese version

## Swizzle组件(高级定制)

Docusaurus允许你”swizzle”(提取)组件进行定制:

代码片段 
npm run swizzle @docusaurus/theme-classic NavbarItem/DocsVersionDropdownNavbarItem --danger

这会将该组件的源代码提取到你的项目中,允许你完全自定义其行为。

## TypeScript支持(高级)

要启用TypeScript支持:

1.安装依赖

代码片段 
npm install --save-dev typescript @types/react @types/react-dom @types/node

2.创建tsconfig.json

代码片段 
{
 "compilerOptions":{
 "target":"es5",
 "lib":["dom","dom.iterable","esnext"],
 "allowJs":true,
 "skipLibCheck":true,
 "strict":true,
 "forceConsistentCasingInFileNames":true,
 "noEmit":true,
 "esModuleInterop":true,
 "module":"esnext",
 "moduleResolution":"node",
 "resolveJsonModule":true,
 "isolatedModules":true,
 "jsx":"preserve",
 "incremental":true,
 },
 "include":["src/**/*"],
}

3.重命名JS文件为TSX

将React组件从.jsx改为.tsx

## Webpack自定义配置(高级)

要扩展Webpack配置,创建webpack.config.js:

代码片段 
module.exports=(config,options)=>{
 config.module.rules.push({
 test:/\.m?js$/,
 exclude:/node_modules\/(?!react-dev-utils|ansi-regex)/,
 use:{
 loader:"babel-loader",    
 options:{      
 presets:[["@babel/preset-env",{targets:"defaults"}]]      
 }    
 }    
});

return config;  
};

## Google Analytics集成(高级)

要添加Google Analytics跟踪代码:

修改docusaurus.config.js

“`javascript {5-9}
themeConfig:{
googleAnalytics:{
trackingID:”UA-XXXXX-Y”,
anonymizeIP:”true”,
},
},

代码片段 

或者使用GTag插件:

 ```javascript {5}
plugins:[    
 "@docusarus-plugin-gtag",    
],    

gtag:{      
 trackingID:"G-XXXXXX",      
 anonymizeIP:"false",      
},

## PWA支持(渐进式Web应用)

让你的站点可以离线访问并添加到主屏幕:

1.安装插件

代码片段 
npm install @docusarus-plugin-pwa --save

2.配置插件

修改dousarus.config.js

“`javascript {5}
plugins:[
“@dousarus-plugin-pwa”,
],

pwa:{
debug:”false”,
offlineModeActivationStrategy:”always”,
swRegisterPath:”service-worker-register.js”,
manifest:{
name:”My Site Name”,
shortname:”SiteName”,
icons:[],
themecolor:#25c2a0,
background_color:#ffffff,
},
},
“`

## PDF导出功能(高级)

要让用户能够导出PDF版本的文档:

1.安装依赖

“`bash
npm install puppeteer marked remark-breaks remark-math rehype-katex gray-matter js-yaml front-matter prismjs highlight.js cheerio axios fs path util stream buffer events http https zlib crypto url querystring os net tls childprocess cluster vm perfhooks async_hooks inspector repl readline tty domain constants assert util types stream webstreams-polyfill text-decoding text-encoding whatwg-url whatwg-fetch abort-controller event-target-shim webidl-conversions browser-process-hrtime web-streams-polyfill encoding fetch-blob formdata-polyfill node-fetch data-urls blob-polyfill webcrypto core-web pure-uuid uuid browserify-sign create-hash create-hmac randombytes public-encrypt private-decrypt diffie-hellman pbkdf2 randomfill cipheriv decipheriv create-cipheriv create-decipheriv create-sign verify create-verify get-ciphers get-curves get-hashes pseudo-random-bytes scrypt generate-keypair generate-keypair-sync rsa-pss rsa-keygen ec-keygen dh-generate-keypair ed25519-keygen x25519-keygen hkdf hmac-drbg drbg hash-wasm hash-wasm-browser md5-wasm sha1-wasm sha256-wasm sha512-wasm ripemd160-wasm whirlpool-wasm sm3-wasm blake2b-wasm blake2s-wasm keccak-wasm shake128-wasm shake256-wasm crypto-browserify crypto-browserify-aes crypto-browserify-des crypto-browserify-dh crypto-browserify-ecdh crypto-browserify-hash crypto-browserify-hmac crypto-browserify-md4 crypto-browserify-md5 crypto-browserify-mgf1 crypto-browserify-pbkdf2 crypto-browserify-publicencrypt crypto-browserify-randombytes crypto-browserify-sign crypto-browserify-stream cipher-base browserify-aes browserify-des browserify-des-ede browserify-des-cbc browserify-des-ecb browserify-des-cfb browserify-des-ofb browserify-des-cfb8 browserify-des-cfb64 browserified-md4 md4 wasm md4 wasm md4 wasm md4 wasm md4 wasm md4 wasm md4 wasm md4 wasm md4 wasm md4 wasm sha256 wasm sha256 wasm sha256 wasm sha256 wasm sha256 wasm sha256 wasm sha256 wasm sha256 wasm sha256 wasm sha512 wasm sha512 wasm sha512 wasm sha512 wassm512wasmsha512wasmsha512wasmsha512wasmsha512wasmsha512wasmsha512wasmsha512wasmsha512wasmsha512wasmsha512wasmsha512wasmsha512wasmsha512wasmsha512wams ripemd160wams ripemd160wams ripemd160wams ripemd160wams ripemd160wams ripemd160wams ripemd160wams ripemd160wams ripemd160wams ripemd160wams whirlpoolwams whirlpoolwams whirlpoolwams whirlpoolwams whirlpoolwams whirlpoolwamswhirlpoolwhirlpoolwhirlpoolwhirlpoolwhirlpoolwhirlpoolwhirlpoolwhirlpools sm3 wamss m3 wamss m3 wamss m3 wamss m3 wamss m3 wamss m3 wamss m3 wamss m3 wamss m3 wamss m3 w ams blake b ws am blake b ws am blake b ws am blake b ws am blake b ws am blake b ws am blake b ws am blake b ws am blake s ws am blake s ws am keccak

原创 高质量