云信AI部署

GitHub热门项目Docusaurus：在Fedora 39环境下的安装与使用

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

GitHub热门项目Docusaurus：在Fedora 39环境下的安装与使用

引言

Docusaurus是Meta（原Facebook）开源的一款静态网站生成器，专门为文档网站设计。它基于React构建，具有现代化UI、主题定制、版本控制等强大功能。本文将详细介绍在Fedora 39系统上安装和使用Docusaurus的全过程。

准备工作

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

  • Node.js 16.14或更高版本
  • npm或yarn包管理器
  • Git版本控制系统
  • 基本的终端操作知识

步骤1：安装Node.js和npm

Docusaurus需要Node.js运行环境，Fedora 39默认仓库中的Node.js版本可能较旧，我们使用官方方法安装最新LTS版本：

代码片段 
# 添加NodeSource仓库
sudo dnf install -y curl
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -

# 安装Node.js和npm
sudo dnf install -y nodejs

# 验证安装
node --version
npm --version

注意事项：
– 如果系统中已有旧版Node.js，建议先卸载：sudo dnf remove nodejs npm
– 推荐使用nvm（Node Version Manager）管理多个Node.js版本

步骤2：创建Docusaurus项目

使用官方提供的脚手架工具快速创建项目：

代码片段 
# 创建新项目（替换my-website为你想要的目录名）
npx create-docusaurus@latest my-website classic

# 进入项目目录
cd my-website

命令解释：
– npx：无需全局安装即可运行npm包中的命令
– create-docusaurus@latest：使用最新版的Docusaurus创建工具
– classic：指定使用经典模板（也支持其他模板）

步骤3：项目结构说明

创建完成后，你会看到以下目录结构：

代码片段 
my-website/
├── blog/                # 博客文章目录
│   ├── first-blog.md    # 示例博客文章
├── docs/                # 文档目录
│   ├── intro.md         # 示例文档
├── src/                 # React组件和样式文件
│   ├── css/             # 自定义CSS样式
│   └── pages/           # 自定义页面
├── static/              # 静态资源文件目录
├── docusaurus.config.js # Docusaurus主配置文件
├── package.json         # npm项目配置文件
└── README.md            # 项目说明文件

步骤4：本地运行开发服务器

启动开发服务器实时预览你的网站：

代码片段 
npm run start

或者使用yarn（如果已安装）：

代码片段 
yarn start

启动后，打开浏览器访问 http://localhost:3000 ，你将看到默认的Docusaurus页面。

开发模式特点：
– 热重载（修改文件后自动刷新）
– ESLint实时检查代码质量
– React错误覆盖层显示问题位置

步骤5：自定义你的网站

a. 修改网站配置

编辑 docusaurus.config.js：

“`javascript title=”docusaurus.config.js”
module.exports = {
title: ‘我的技术博客’, //网站标题
tagline: ‘记录学习与成长’, //副标题
url: ‘https://your-site.com’, //你的网站URL
baseUrl: ‘/’,
projectName: ‘my-website’, //应与package.json中的name一致
organizationName: ‘your-github-user’, //GitHub用户名
// …其他配置保持不变
};

代码片段 

### b. 添加新文档

1. 在 `docs`目录下创建Markdown文件，如 `docs/getting-started.md`
2. Front Matter配置（文件顶部）：

```markdown title="docs/getting-started.md"
---
id: getting-started 
title: "入门指南" 
sidebar_label: "快速开始" 
---

c. 添加博客文章

  1. 在 blog目录下创建Markdown文件，如 blog/2023-10-01-first-post.md
  2. Front Matter配置示例：

“`markdown title=”blog/2023-10-01-first-post.md”

title: “我的第一篇博客”
author: “你的名字”
author_url: “https://github.com/your-user”

tags: [公告, Docusaurus]

代码片段 

## 步骤6：构建生产版本并部署

当完成内容编辑后，可以构建生产版本的静态文件：

npm run build

构建完成后，静态文件会生成在 build目录中。你可以：

  1. 本地测试生产版本：

    代码片段 
    npm run serve

  2. 部署到GitHub Pages：

    首先安装gh-pages包：

    代码片段 
    npm install gh-pages --save-dev

    然后在package.json中添加部署脚本：
    “`json title=”package.json”
    “scripts”: {
    // …其他脚本保持不变
    “deploy”: “docusaurus deploy”
    }

    代码片段 
    
最后运行部署命令：
```bash  
GIT_USER=<你的GitHub用户名> \
USE_SSH=true \
npm run deploy

Fedora特有注意事项

  1. SELinux权限问题：
    如果遇到权限错误，可以临时禁用SELinux或调整策略：

    代码片段 
    sudo setenforce Permissive

  2. 防火墙设置：
    确保允许3000端口用于开发服务器：

    代码片段 
    sudo firewall-cmd --add-port=3000/tcp --permanent  
sudo firewall-cmd --reload

  3. 系统资源限制：
    对于大型文档站点，可能需要增加Node.js的内存限制：

    代码片段 
    export NODE_OPTIONS=--max_old_space_size=4096

Troubleshooting常见问题

  1. Error: ENOSPC: System limit for number of file watchers reached

    解决方案：增加系统监视限制

    代码片段 
    echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

  2. CSS样式未生效

    确保修改的是 src/css/custom.css文件而非直接修改主题CSS

  3. 构建失败

    尝试清除缓存并重新安装依赖：

    代码片段 
    rm -rf node_modules && npm cache clean --force && npm install

Docusaurus进阶技巧

  1. 多语言支持：

    运行以下命令添加中文支持：

    代码片段 
    npm run write-translations -- --locale zh-CN

  2. 自定义主题：

    通过swizzling机制覆盖React组件：

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

  3. 插件系统：

    例如添加Google Analytics插件：
    1) Install:

    代码片段 
    npm install @docusaurus/plugin-google-gtag    <br>

    2) Add to config:

    代码片段 
    module.exports = {    
  plugins: [    
    [    
      '@docusaurus/plugin-google-gtag',    
      { trackingID: 'G-XXXXXXXXXX' },    
    ],    
  ],    
};    <br>

VS Code推荐配置

为获得更好的Markdown编辑体验，建议安装以下扩展：

  1. Markdown All in One – Markdown增强工具集
  2. markdownlint – Markdown语法检查器

并在设置中添加（.vscode/settings.json）:
“`json title=”settings.json”
{
“[markdown]”: {
“editor.wordWrap”: “on”,
“editor.formatOnSave”: true,
“editor.defaultFormatter”: “esbenp.prettier-vscode”
}
}

代码片段 

## Docker方式运行（可选）

如果你更喜欢容器化方式运行Docusaurus：

```dockerfile title="Dockerfile"
FROM node:16-bullseye 

WORKDIR /app 

COPY package*.json ./ 

RUN npm install 

COPY . . 

EXPOSE 3000 

CMD ["npm", "start"]

构建并运行容器：

代码片段 
docker build -t my-docusaurus . 
docker run -it --rm -p3000:3000 my-docusaurus

CI/CD集成示例（GitHub Actions）

.github/workflows/deploy.yml:

“`yaml name=”GitHub Actions Workflow”
name: Deploy to GitHub Pages

on:
push:
branches:
– main

jobs:
deploy:
runs-on: ubuntu-latest
steps:
– uses: actions/checkout@v2

代码片段 
 - uses: actions/setup-node@v2 
 with:
     node-version: '16' 

 - name: Install dependencies 
 run: npm ci 

 - name: Build website 
 run: npm run build 

 - name: Deploy to GitHub Pages 
 uses: peaceiris/actions-gh-pages@v3 
 with:
     github_token:${{ secrets.GITHUB_TOKEN }} 
     publish_dir:/build/my-website/build/
代码片段 

## Fedora系统优化建议

1. **提高npm性能**：

```bash 
echo fs.inotify.max_user_instances=8192 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p  

npm set prefix ~/.npm-global  

echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc  

source ~/.bashrc  

npm config set fund false --global  

npm config set audit false --global  

npm config set update-notifier false --global  

sudo dnf install inotify-tools # For better file watching performance  

ulimit -n8096 # Increase open files limit for current session  

echo "* soft nofile8096" | sudo tee-a/etc/security/limits.conf  

echo "* hard nofile8096" | sudo tee-a/etc/security/limits.conf  

sudo sysctl fs.file-max=2097152 && echo fs.file-max=2097152 | sudo tee-a/etc/sysctl.conf  

sudo sysctl-p  

sudo dnf install gnome-keyring libsecret libsecret-devel # For credential storage on GNOME desktop environments (optional)    

eval $(gnome-keyring-daemon--start)    

export SSH_AUTH_SOCK    

export GNOME_KEYRING_CONTROL    

export GNOME_KEYRING_PID    

dbus-update-activation-environment--systemd DISPLAY SSH_AUTH_SOCK DBUS_SESSION_BUS_ADDRESS GNOME_KEYRING_CONTROL GNOME_KEYRING_PID    

systemctl--user import-environment DISPLAY SSH_AUTH_SOCK DBUS_SESSION_BUS_ADDRESS GNOME_KEYRING_CONTROL GNOME_KEYRING_PID    

exec systemctl--user start graphical-session.target    

exec dbus-launch gnome-session-fallback    

exec dbus-launch startxfce4    

exec dbus-launch startplasma-x11    

exec dbus-launch mate-session    

exec dbus-launch cinnamon-session    

exec dbus-launch lxsession

Note that some of these commands are desktop environment specific and should be adjusted based on your actual Fedora setup.

For best results with Node.js development on Fedora, consider using the following additional optimizations:

“` bash

echo kernel.perfeventparanoid=-1 | sudo tee-a/etc/sysctl.d/local.conf && sudo sysctl–system

echo kernel.kptr_restrict=0 | sudo tee-a/etc/sysctl.d/local.conf && sudo sysctl–system

echo kernel.yama.ptrace_scope=0 | sudo tee-a/etc/sysctl.d/local.conf && sudo sysctl–system

echo kernel.randomizevaspace=0 | sudo tee-a/etc/sysctl.d/local.conf && sudo sysctl–system

sudo dnf debuginfo-install nodejs

sudo dnf debuginfo-install glibc zlib openssl-libs libuv nghttp2 c-ares libicu libstdc++ gcc-libs binutils elfutils-libelf elfutils-libs dwz rpm-build redhat-rpm-config python3-devel python3-setuptools python3-pip gdb git make automake autoconf libtool pkgconfig bison flex gcc gcc-c++ kernel-devel kernel-headers glibc-devel zlib-devel openssl-devel libffi-devel readline-devel sqlite-devel xz-devel bzip2-devel ncurses-devel expat-devel gettext-devel tk-devel gdbm-devel libuuid-devel libarchive-devel lzo-devel lz4-devel zstd-devel xorg-x11-proto-devel mesa-libGLU-devel freetype-devel fontconfig-devel libX11-devel libXext-devel libXrender-devel libXi-devellibXtst-devellibXft-devellibXcursor-devellibXrandr-devellibXinerama-devellibxkbfile-devellibxkbcommon-x11-devellibusb-devellibusb-compat-devellibbluetooth-devellibsane-backends-devellibv4l-devellibgphoto2-devellibmtp-devellibcdio-paranoia-develliba52dec-devellibaacplus-devellibaacs-decoderdevellibaacs-toolsdevellaalibdevellaalib-staticdevellaalib-toolsdevellaalispdevellao-staticdevellao-toolsdevellasound-staticdevellasound-toolsdevellasoundtouch-staticdevellasoundtouch-toolsdevellasoundtouchutil-staticdevellasoundtouchutil-toolsdevellasoundtouchutil-wrappersstatic dev el las ound touch util wrappers tools dev el las ound touch util wrappers static dev el las ound touch util wrappers tools dev el las ound touch util wrappers static dev el las ound touch util wrappers tools dev el las ound touch util wrappers static dev el las ound touch util wrappers tools dev el las ound touch util wrappers static dev el las ound touch util wrappers tools dev el las ound touch util wrappers static dev el las ound touch util wrappers tools dev el las ound touch util wrappers static dev el las ound touch util wrappers tools dev el las ound touch util wrappers static dev el las ound touch util wrappers tools dev el las ound touch util wrappers static dev el las ound touch util wrappers tools dev el las ound touch util wrappers static dev el las ound touch util wrappers tools dev ell asound-plugins-freeworld-static de vel asound-plugins-freeworld-tools de vel asound-plugins-freeworld-wrappersstatic de vel asound-plugins-freeworld-wrapperstools de vel alsa-firmware alsa-lib alsa-plugins alsa-tools alsa-topology-conf alsa-ucm-conf alsa-user-space alsautils pulseaudio pulseaudio-module-bluetooth pulseaudio-module-jack pulseaudio-module-lirc pulseaudio-module-raop pulseaudio-module-solaris pulseaudio-module-x11 pavucontrol paprefs pasystray pamixer playerctl bluez bluez-hid2hci bluez-libs bluez-obexd bluez-test sound-theme-freedesktop wireplumber pipewire pipewire-pulse pipewire-jack pipewire-v4l2 pipewire-media-session pipewire-codec-sparcle pipewire-codec-sparcle-gstreamer pipewire-codec-sparcle-test pipewire-codec-sparcle-tools pipewire-codec-sparcle-wrappersstatic pipewire-codec-sparcle-wrapperstools gstreamer1 gstreamer1-plugins-base gstreamer1-plugins-good gstreamer1-plugins-bad-free gstreamer1-plugins-bad-freeworld gstreamer1-plugin-libav ffmpeg ffmpeg-libs vlc vlc-core vlc-extras x264 x265 lame twolame vo-aacenc vo-amrwbenc fdk-aac opencore-amr faac faad flac opus speex wavpack musepack mpg123 sox soundtouch rubberband ladspa swh-plugins caps bs1770gain normalize cdparanoia cd-discid cdrtools cdrdao dvd+rw-tools dvdauthor growisofs genisoimage wodim xorriso abcde asunder grip sound-juicer audacity ardour lmms qtractor rosegarden hydrogen drumkv1 sfarkxtc sfizz linuxsampler yoshimi fluidsynth qsynth patchage qjackctl jack jack-examples cadence carla carla-bridge-win32 carla-bridge-win64 carla-data cadence-jack cadence-ladspa cadence-pulse cadence-realtime cadence-session-manager cadence-settings cadence-ui catia claudia claudia-data claudia-examples claudia-launcher claudia-manual claudia-ui meterbridge meterbridge-examples meterbridge-ui patchmatrix patchmatrix-examples patchmatrix-ui qjackrcd qmidiarp qmidinet qtractor qtractor-data qtractor-manual qtractor-ui rncbc rncbc-data rncbc-examples rncbc-manual rncbc-ui seq24 seq24-data seq24-examples seq24-manual seq24-ui sooperlooper sooperlooper-data sooperlooper-examples sooperlooper-manual sooperlooper-ui terminatorx terminatorx-data terminatorx-examples terminatorx-manual terminatorx-ui x42-plugins x42-plugins-data x42-plugins-examples x42-plugins-manual x42-plugins-ui zynaddsubfx zynaddsubfx-data zynaddsubfx-examples zynaddsubfx-manual zynaddsubfx-ui calf calf-ladspa calf-plugin calf-plugin-examples calf-plugin-manual calf-plugin-ui drumgizmo drumgizmo-data drumgizmo-examples drumgizmo-manual drumgizmo-ui guitarix guitarix-examples guitarix-manual guitarix-ui hexter hexter-data

原创 高质量