第四课：内置搜索

（一）Screen 脚本

Docusaurus 是 自带搜索功能 的，需要手动启用。Docusaurus 从 v2.4 开始内置了本地搜索插件 @cmfcmf/docusaurus-search-local，适合不想接入 Algolia 的用户。

在你的 Docusaurus 项目根目录 D:\Notes\my-docs 下运行：

npm install @easyops-cn/docusaurus-search-local

然后修改 docusaurus.config.js 添加插件配置：

当前的 config 中没有 plugins: [] 字段。我们可以在 export default { ... } 最外层添加一个 plugins 字段。

const config = {
  // ...你的原始配置不变

  presets: [
    // ...原样保留
  ],

  plugins: [
      [
        require.resolve('@easyops-cn/docusaurus-search-local'),
        {
          indexDocs: true,
          indexPages: true,
          language: ['zh', 'en'],
        },
      ],
    ],


  themeConfig: {
    // ...保留你已有的 themeConfig
  },
};

重启服务器即可。

现在你可以在网页右上角看到搜索框了，支持模糊匹配所有文档标题和正文内容。但是现在的搜索框是不能用的，因为当前的启动命令是： npm start，是开发者模式。本地搜索插件在开发模式下 默认不会生成搜索索引，只在 npm run build 的时候生成。因此需要 运行正式构建命令 + 本地预览

我们编写一个脚本：build-serve.bat（用于测试搜索功能）

@echo off
cd /d D:\Notes\my-docs

echo Cleaning cache and previous build...
if exist .docusaurus ( rd /s /q .docusaurus )
if exist build ( rd /s /q build )

echo Building site...
call npm run build

echo Starting local server on http://localhost:4090 ...
call npx docusaurus serve --port 4090 --no-open

pause

解释：

npm run build 本身是一个 Node 子进程，.bat 脚本在执行 npm run build 时 如果出错（比如有 broken link 警告），就会直接跳出，不执行后面的命令。因此要加上 call ，可以让批处理脚本在子命令执行后继续执行后面的命令。
pause 放在最后，保持窗口不关闭，方便你看到最终输出

注意：

在 正式构建 情况下，不具有开发模式的实时修改更新功能！

放到 Ubuntu 上改成 build-serve.sh

#!/bin/bash

# 切换到 Docusaurus 目录
cd /mnt/d/Notes/my-docs || exit 1

echo "Cleaning cache and previous build..."
rm -rf .docusaurus
rm -rf build

echo "Building site..."
npm run build

echo "Starting Docusaurus server inside screen session: docusaurus"
# 如果已有同名 screen 先关闭
screen -S docusaurus -X quit 2>/dev/null

# 创建新的 screen 会话并启动服务器
screen -dmS docusaurus bash -c "npx docusaurus serve --port 4090 --no-open"

echo "Server is running on http://localhost:4090 (inside screen session: docusaurus)"

（二）系统服务

但是由于笔记内容一直在更新，所以我打算让其每天凌晨 4 点准时自动重启，或者自动重新编译。最好能添加成系统服务，该怎么做？

我们需要把 screen 去掉，用 systemd 管理服务进程，定时 04:00 “重编译 + 重启”用 systemd timer

建议把 build-serve.sh 改为只负责 build，然后把 “serve” 交给 systemd 服务。

1. 本地脚本

新建两个脚本（也可以在原脚本基础上拆分）：

/mnt/d/Notes/my-docs/scripts/docusaurus-build.sh

#!/bin/bash
set -euo pipefail

export HOME="/home/heihe"
export USER="heihe"

export NVM_DIR="/home/heihe/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

cd /mnt/d/Notes/my-docs

echo "[docusaurus] Cleaning cache..."
rm -rf .docusaurus

echo "[docusaurus] Building site..."
npm run build

这样 build 期间不会把当前 build/ 目录删掉，站点不会因为 rebuild 过程短暂下线。 npm run build 会覆盖/更新 build 输出。

/mnt/d/Notes/my-docs/scripts/docusaurus-serve.sh

#!/bin/bash
set -euo pipefail

export HOME="/home/heihe"
export USER="heihe"

cd /mnt/d/Notes/my-docs

# 用项目本地依赖启动，避免 systemd 下找不到 npx
exec npm run serve -- --port 4090 --no-open

赋权：

chmod +x /mnt/d/Notes/my-docs/scripts/docusaurus-*.sh

2. 系统服务

查一下 npm 在哪：

which npm
which node

输出是

/home/heihe/.nvm/versions/node/v20.19.5/bin/npm
/home/heihe/.nvm/versions/node/v20.19.5/bin/node

输出不是 /usr/bin/npm 和 /usr/bin/node，说明你这是 nvm 安装的 Node，所以 systemd 默认 PATH 找不到 npm/npx。最稳的做法是：在 service 里显式指定 PATH 指向该 nvm 版本的 bin（同时可选加上 NVM_DIR），这样无需依赖 .bashrc。

sudo vim /etc/systemd/system/docusaurus.service

内容改成（重点看 Environment=PATH=...）：

[Unit]
Description=Docusaurus server (serve build output)
After=network.target

[Service]
Type=simple
User=heihe
WorkingDirectory=/mnt/d/Notes/my-docs

Environment=HOME=/home/heihe
Environment=USER=heihe
Environment=NODE_ENV=production
Environment=NVM_DIR=/home/heihe/.nvm
Environment=PATH=/home/heihe/.nvm/versions/node/v20.19.5/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

ExecStart=/mnt/d/Notes/my-docs/scripts/docusaurus-serve.sh

Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

然后执行：

sudo systemctl daemon-reload
sudo systemctl restart docusaurus.service
sudo systemctl status docusaurus.service --no-pager
journalctl -u docusaurus.service -n 80 --no-pager

停止服务

sudo systemctl stop docusaurus.service
sudo systemctl reset-failed docusaurus.service

3. 定时任务

目标加工后

**docusaurus.service **👉 常驻服务，负责 serve
**docusaurus-rebuild.service **👉 一次性任务（oneshot），负责 build + restart
**docusaurus-rebuild.timer **👉 systemd 定时器，每天 04:00 触发 rebuild

创建「重编译 + 重启」的 oneshot service

sudo vim /etc/systemd/system/docusaurus-rebuild.service

[Unit]
Description=Rebuild Docusaurus site and restart server
Wants=docusaurus.service

[Service]
Type=oneshot
User=heihe
PermissionsStartOnly=true
WorkingDirectory=/mnt/d/Notes/my-docs

Environment=HOME=/home/heihe
Environment=USER=heihe

Environment=NODE_ENV=production
Environment=NVM_DIR=/home/heihe/.nvm
Environment=PATH=/home/heihe/.nvm/versions/node/v20.19.5/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

ExecStart=/mnt/d/Notes/my-docs/scripts/docusaurus-build.sh
ExecStartPost=/bin/systemctl restart docusaurus.service

加载：

sudo systemctl daemon-reload

创建 systemd timer（每天凌晨 4 点） /etc/systemd/system/docusaurus-rebuild.timer

[Unit]
Description=Daily rebuild for Docusaurus at 04:00

[Timer]
OnCalendar=*-*-* 04:00:00
Persistent=true
Unit=docusaurus-rebuild.service

[Install]
WantedBy=timers.target

启用并立即生效：

sudo systemctl enable --now docusaurus-rebuild.timer
systemctl list-timers --all | grep docusaurus

4. 立刻验证

手动触发一次 rebuild（模拟凌晨 4 点）

sudo systemctl start docusaurus-rebuild.service

这个命令执行完大概要 4 分钟左右。

查看日志：

journalctl -u docusaurus-rebuild.service --no-pager -n 100

确认 timer 已正确注册

systemctl list-timers --all | grep docusaurus

你应该看到类似：

docusaurus-rebuild.timer  Thu 2026-01-16 04:00:00 CST  ...

（一）Screen 脚本​

（二）系统服务​

1. 本地脚本​

2. 系统服务​

3. 定时任务​

4. 立刻验证​