Node.js 版本必须 ≥18.0，否则 npx create-docusaurus@latest 会静默失败：目录创建成功但关键依赖（如 @docusaurus/core）未安装，导致后续 yarn start 报错“Cannot find module”。
Node.js 版本必须 ≥18.0，create-docusaurus 会静默失败
用 npx create-docusaurus@latest my-site classic 初始化项目时，如果系统里装的是 Node.js 16 或更低版本，命令可能看似执行成功、目录也建了，但 package.json 里关键依赖（比如 @docusaurus/core）压根没装上，后续 yarn start 直接报 Cannot find module '@docusaurus/core'。
验证方式很简单：node -v 输出必须是 v18.x 或 v20.x。CentOS/Ubuntu 上别信系统包管理器默认的 nodejs 包——它常是 14 或 16；老老实实用 Nodesource 官方源：
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash - sudo yum install -y nodejs npm
Windows 用户直接去 nodejs.org 下载 LTS（当前是 20.x），别用 Microsoft Store 里的版本，那个更新滞后且权限异常多。
VSCode 必须启用 Remote-SSH 才能高效编辑远程 Docusaurus 项目
如果你把 Docusaurus 项目部署在 ECS 或自建服务器上（比如 CentOS 8 Stream），本地用 VSCode 编辑，就别拖文件来回同步了——Remote-SSH 插件才是正解。
- 先在 VSCode 扩展市场搜
Remote-SSH，装好 - 按
Ctrl+Shift+P→ 输入Remote-SSH: Connect to Host...→ 添加你的服务器地址（如user@192.168.1.100） - 连接后，用
File → Open Folder直接打开服务器上的/var/www/my-site目录 - 此时所有保存、终端命令（比如
yarn start）都跑在远程，热重载毫秒级响应，不用等 FTP 同步
注意：Xshell/Xftp 配合 VSCode 编辑器设置（比如在 Xftp 中右键“在 VSCode 中编辑”）容易因编码或换行符出问题，不如一步到位用 Remote-SSH。
yarn start 报错 EADDRINUSE？检查端口和 baseUrl 冲突
Docusaurus 默认启动在 http://localhost:3000，但如果你改过 docusaurus.config.js 里的 baseUrl（比如设成 /docs/），又没配好本地开发服务器路径，浏览器打开后白屏、控制台报 404，或者 yarn start 直接卡住不动。
常见坑点：
-
baseUrl必须以/开头、结尾不能有斜杠（baseUrl: '/my-blog'✅，baseUrl: 'my-blog/'❌） - 本地开发时
baseUrl建议保持默认/，上线再改；否则要手动加serve -s build -p 3000模拟子路径 - 端口被占？查
lsof -i :3000（macOS/Linux）或netstat -ano | findstr :3000（Windows），杀掉对应 PID
中文搜索失效？别漏掉 @docusaurus/plugin-client-redirects 和语言配置
很多人照着文档配了 i18n，zh-Hans 文件夹也放进了 i18n/zh-Hans/docusaurus-plugin-content-docs，但搜索框还是只搜英文内容，输入中文没结果。
根本原因：Docusaurus 的中文搜索依赖两个插件协同工作：
-
@docusaurus/plugin-client-redirects：处理路由跳转（尤其多语言下页面路径映射） -
@docusaurus/theme-search-algolia或本地@easyops-cn/docusaurus-search-local（推荐后者，免配 Algolia）
在 docusaurus.config.js 的 plugins 数组里补全：
plugins: [
[
'@easyops-cn/docusaurus-search-local',
{{"indexDocs": true, "indexBlog": false}},
],
],同时确认 i18n 配置中 defaultLocale 和 locales 一致，且 themeConfig 下的 navbar 和 footer 文案已翻译进对应语言 JSON 文件——否则导航栏中文显示正常，但搜索索引仍按英文 key 构建。
最易被忽略的一点：每次改完 i18n 或搜索插件配置，必须删掉 build/ 和 node_modules/.cache 目录再 yarn build，否则旧缓存会让中文搜索持续失效。
