如何在 Docusaurus 文档站点中安全、可维护地注入自定义脚本

本文介绍在 Docusaurus 2.x 中为文档页面添加自定义 JavaScript 的标准实践，强调避免直接修改 node_modules，推荐使用 static/ 目录 + docusaurus.config.js 中的 scripts 配置实现零侵入、可部署、易维护的脚本集成方案。

本文介绍在 docusaurus 2.x 中为文档页面添加自定义 javascript 的标准实践，强调避免直接修改 node_modules，推荐使用 `static/` 目录 + `docusaurus.config.js` 中的 `scripts` 配置实现零侵入、可部署、易维护的脚本集成方案。

在 Docusaurus 中注入第三方或自定义脚本（如分析埋点、客服 Widget、交互式图表初始化逻辑等），*绝不可通过手动修改 `node_modules/@docusaurus/theme-中的模板文件实现**——此类操作不仅会在npm install` 后丢失，更会导致升级困难、CI/CD 失败及团队协作风险。

✅ 正确做法是遵循 Docusaurus 官方推荐的静态资源加载机制：

wisecut

一款在线视频编辑软件，使用AI和语音识别为你编辑视频

下载

1. 将脚本放入 static/ 目录
   在项目根目录下创建 static/js/analytics.js（路径可自定义）：

   // static/js/analytics.js
   document.addEventListener('DOMContentLoaded', () => {
     console.log('[Docusaurus] Custom script loaded successfully');
     // 你的业务逻辑，例如初始化 GA4 或监听页面路由变化
     window.addEventListener('docusaurus.routeChange', ({ pathname }) => {
       console.log('Route changed to:', pathname);
     });
   });

2. 在 docusaurus.config.js 中声明脚本
   使用 scripts 配置项（支持数组，按顺序加载）：

   module.exports = {
     // ... 其他配置
     scripts: [
       {
         src: '/js/analytics.js', // 注意：路径以 '/' 开头，对应 static/ 下的相对路径
         async: false,           // 默认 false；设为 true 可异步加载（不阻塞渲染）
         defer: true,            // 推荐启用，确保 DOM 解析完成后再执行
       },
       // 可追加 CDN 脚本，如：
       // 'https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.js'
     ],
   };

⚠️ 关键注意事项：

• 所有 static/ 下的文件会自动映射为 /[path]，例如 static/js/app.js → 可通过 /js/app.js 访问；
• scripts 数组中的路径必须为绝对 URL 路径（以 / 开头）或完整外部 URL；
• 若脚本依赖 window 或 DOM，务必包裹在 DOMContentLoaded 或 docusaurus.routeChange 事件中（Docusaurus 使用客户端路由）；
• 生产构建时，Docusaurus 会自动内联 scripts 列表中的本地脚本（若未设置 async: true），无需额外配置打包工具。

? 进阶提示：对于需服务端注入的场景（如 SEO 友好的初始数据），可结合 clientModules 或自定义 Html.js 布局组件，但绝大多数前端增强需求，scripts 配置已完全满足——简洁、稳定、符合框架设计哲学。