启动egjs-flicking文档时出现找不到sidebars-api.js模块错误

问题 #

克隆egjs-flicking的GitHub仓库后，按README指引操作：

• 根目录执行npm install安装根路径依赖
• 进入docs目录执行yarn install && yarn start启动文档服务

启动时出现模块找不到错误，全局搜索项目未找到sidebars-api.js文件，原本以为Docusaurus会自动生成该文件，尝试升级/降级Docusaurus版本后问题依旧。

错误信息 #

[ERROR] Sidebars file at "/egjs-flicking/egjs-flicking/docs/sidebars.js" failed to be loaded.
[ERROR] Loading of version failed for version current
[ERROR] Error: Cannot find module './sidebars-api.js'
Require stack:
- /egjs-flicking/egjs-flicking/docs/sidebars.js
- /egjs-flicking/egjs-flicking/docs/node_modules/@docusaurus/plugin-content-docs/lib/sidebars/index.js
- /egjs-flicking/egjs-flicking/docs/node_modules/@docusaurus/plugin-content-docs/lib/index.js
- /egjs-flicking/egjs-flicking/docs/node_modules/@docusaurus/core/lib/server/plugins/configs.js
- /egjs-flicking/egjs-flicking/docs/node_modules/@docusaurus/core/lib/server/plugins/init.js
- /egjs-flicking/egjs-flicking/docs/node_modules/@docusaurus/core/lib/server/plugins/index.js
- /egjs-flicking/egjs-flicking/docs/node_modules/@docusaurus/core/lib/server/index.js
- /egjs-flicking/egjs-flicking/docs/node_modules/@docusaurus/core/lib/commands/build.js
- /egjs-flicking/egjs-flicking/docs/node_modules/@docusaurus/core/lib/index.js
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:933:15)
    at Function.Module._load (node:internal/modules/cjs/loader:778:27)
    at Module.require (node:internal/modules/cjs/loader:1005:19)
    at require (node:internal/modules/cjs/helpers:102:18)
    at Object.<anonymous> (/egjs-flicking/egjs-flicking/docs/sidebars.js:8:6)
    at Module._compile (node:internal/modules/cjs/loader:1105:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1159:10)
    at Module.load (node:internal/modules/cjs/loader:981:32)
    at Function.Module._load (node:internal/modules/cjs/loader:822:12)
    at Module.require (node:internal/modules/cjs/loader:1005:19)

相关文件内容 #

docs/sidebars.js

module.exports = {
  docs: [
    {
      type: "autogenerated",
      dirName: "tutorials"
    }
  ],
  ...require("./sidebars-api.js")
};

docs/package.json

{
  "name": "docs",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start --host 0.0.0.0",
    "build": "docusaurus build",
    "swizzle": "docusaurus swizzle --danger",
    "deploy": "docusaurus deploy",
    "clear": "docusaurus clear",
    "serve": "docusaurus serve",
    "write-translations": "docusaurus write-translations",
    "write-heading-ids": "docusaurus write-heading-ids"
  },
  "dependencies": {
    "@docusaurus/core": "^2.2.0",
    "@docusaurus/preset-classic": "^2.2.0",
    "@egjs/flicking-plugins": "^4.4.0",
    "@egjs/react-flicking": "^4.10.2",
    "@egjs/react-grid": "^1.1.2",
    "@mdx-js/react": "^1.6.21",
    "bulma": "^0.9.2",
    "clsx": "^1.1.1",
    "docusaurus-plugin-sass": "^0.1.15",
    "docusaurus-plugin-sidebar": "^1.0.3",
    "react": "^17.0.1",
    "react-dom": "^17.0.1",
    "react-tabs": "^3.2.2",
    "react-toggle": "^4.1.2"
  },
  "browserslist": {
    "production": [
      ">0.5%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  },
  "devDependencies": {
    "@babel/plugin-proposal-class-properties": "^7.14.5",
    "@babel/plugin-proposal-decorators": "^7.13.15",
    "@types/react": "^17.0.19",
    "remark-breaks": "^2.0.2"
  }
}

解决方案 #

核心问题是sidebars-api.js并非Docusaurus自动生成的文件，而是egjs-flicking项目通过自定义脚本生成的API侧边栏配置文件，可按以下方式处理：

• 执行根目录生成脚本
  查看根目录package.json中的scripts字段，寻找类似build:api或generate:sidebar的命令，执行该命令即可自动生成docs/sidebars-api.js文件。

• 临时修复（快速启动）
  若仅需查看教程内容，可修改docs/sidebars.js，移除对缺失文件的引用：

  module.exports = {
    docs: [
      {
        type: "autogenerated",
        dirName: "tutorials"
      }
    ]
  };
  

  修改后重新执行yarn start即可启动文档服务，但API相关侧边栏会缺失。

• 检查根目录依赖安装
  确保根目录npm install执行过程无报错，部分项目会在根依赖安装完成后自动触发API文档生成脚本，若安装失败可能导致生成步骤未执行。

内容的提问来源于stack exchange，提问作者Riru setine