常见问题
大部分问题都可以在文档中找到解决办法，请优先从 快速开始 阅读文档，再进行实际操作。
如果还是运行报错，请 提交 issue 或在 discussions 中留言
配置问题
elog.config.js为 Elog 的配置文件，其中以 process.env开头的不需要改动，且为必填信息。
例如 process.env.YUQUE_TOKEN为语雀账号相关敏感信息，用于本地同步时在.elog.env中指定YUQUE_TOKEN=你的语雀 Token，其他配置可根据实际需求改动。
Elog 运行报缺少参数
- 检查
elog.config.js中所有platform属性的值是否是你对应平台的值。例如如果想用语雀 Token 的方式同步语雀文档，则write.platform = yuque；如果是使用语雀账号密码的方式，则write.platform = yuque-pwd - 检查
.elog.env中是否填写账号信息。无论用哪种方式同步语雀，.elog.env中的YUQUE_LOGIN和YUQUE_REPO都是必填参数。其他必填参数请看本文档相关配置表格中的是否必填字段
如何重新全量同步文档
elog 默认为增量更新，只有该文档重新修改过，再次同步时，才会重新拉取该文档。如果想重新全量同步文档。有以下 3 种办法：
- 运行同步命令时，增加禁用缓存标识：
elog sync --disable-cache - 运行
elog clean，Elog 将会自动清除所有文档、本地图片、缓存文件(elog.cache.json) elog.cache.json为 Elog 增量同步的关键，可手动删除此文件，推荐同时手动删除所有文档、本地图片
语雀/飞书子目录没有导出
默认是没有按目录导出的，可通过配置开启：按目录存放文档
如何升级 Elog 到指定版本
运行
elog upgrade更新全局 Elog 版本到最新正式版本如果你是通过包管理工具（
npm/yarn/pnpm）全局安装的 Elog，则重新安装并指定版本号shellnpm install @elog/cli@0.9.1 -g # 也可以指定测试版本号 npm install @elog/cli@0.9.1-beta.4 -g如果你是将 Elog安装在
package.json中，则修改package.json中的@elog/cli版本号
全局安装和局部安装 Elog 的区别
全局安装 Elog
全局安装指的是为电脑的全局环境安装，安装后可以在任意文件夹使用 Elog 相关命令。全局安装时需要指定 -g 参数，例如
# 全局安装 elog 最新正式版本
npm install @elog/cli -g
# 也可以指定测试版本号全局安装
npm install @elog/cli@0.11.0-beta.1 -g
# 查看当前 elog 版本
elog --version
# 运行同步
elog sync -e .elog.env全局安装一般适用于本地同步时使用，如果想结合 Github Actions 实现自动化文档同步，建议采取局部安装的方式
局部安装 Elog
局部安装指的是为指定文件夹下的环境安装Elog，需要结合 npm 相关知识点，将 Elog 安装在package.json中。局部安装不需要指定-g参数，例如
# 局部安装 elog 最新正式版本
npm install @elog/cli
# 也可以指定测试版本号局部安装
npm install @elog/cli@0.11.0-beta.1安装在 package.json中的 Elog 在使用时需要提前在npm scripts中指定相关运行命令，例如
// package.json
{
"scripts": {
"build": "vitepress or hexo 或者其他自定义的命令，具体以自己的工具为准", // 构建文档
"sync:local": "elog sync -e .elog.env", // 本地同步时需要从env中取值
"sync": "elog sync", // 进行同步
"clean": "elog clean"
}
}然后就可以命令行下使用npm run命令，执行提前定义的脚本
npm run sync:local
# 命令等同于执行
elog sync -e .elog.env
npm run执行时会使用安装在package.json中的 Elog 版本。而直接使用elog sync -e .elog.env使用的是安装在电脑全局环境的 Elog，需要注意区分。
如果你两种方式都安装了，尽量保证全局 Elog 版本和package.json中的 Elog 版本保持一致
局部安装 Elog 的好处在于，如果你使用的是vitepress/hexo 等基于 JavaScript 的博客平台，那么他们天然会有 package.json文件。你只需要npm install @elog/cli局部安装 Elog，然后配置相关命令脚本，npm run运行同步命令即可。而使用 Github Actions 也不用额外全局安装 @elog/cli 了
总之，如果你不准备使用 Github Actions，则全局安装 Elog 即可。
如果你需要结合 Github Actions实现文档自动化更新，请先阅读阮一峰的npm scripts 使用指南，再进行实践，并结合大家的最佳实践来操作。
如何同步多个知识库/数据表
在语雀中， Elog 是以知识库为维度进行同步，一次只能同步一个知识库。
如果想要同时同步多个知识库：
复制
elog.config.js和.elog.env，并改名为elog-xxx.config.js和.elog-xxx.env；在
elog-xxx.config.js配置文件中指定另外一个知识库的导出目录(deploy.local.outputDir)；在
.elog-xxx.env指定另一个知识库的repo、login等相关值。并在运行同步命令时指定相关参数：
shell# 此命令表示，将使用.elog-xxx.env中的账号信息， # 指定读取elog-xxx.config.js中的配置， # 并将缓存文件命名为elog-xxx.cache.json elog sync -e .elog-xxx.env -a elog-xxx.cache.json -c elog-xxx.config.js
在 Notion 或其他写作平台也是如此，需要指定不同的配置文件(elog.config.js)、缓存文件(elog.cache.json)、本地环境变量文件(.elog.env)。
如果有使用 github，请不要将
.elog.env配置文件上传到 github，需要在.gitignore中忽略此文件
具体可参考 本文档（Elog-Docs）源码：https://github.com/LetTTGACO/elog-docs
elog运行时找不到该命令
- 检查是否全局安装过 elog
- 重启命令行工具，如果全局安装过也运行不了，大概率是命令行工具的配置的问题。可采用备用方案：将
elog运行命令改为npx @elog/cli
# 初始化 elog 配置文件
npx @elog/cli init
# 本地同步命令
npx @elog/cli sync -e .elog.env
# 清除本地缓存
npx @elog/cli clean同步时卡住不动
- 在Github自动化流程中同步卡住
- 本地同步运行时卡住
- 图片下载时卡住
- 文档下载时卡住
解决办法
在全量同步时，因为语雀/FlowUs为国内平台，有时会在Github等国外环境运行时由于网络问题卡住。此时可以在本地先手动运行一遍，提交缓存文件到Github，后续的增量同步会快很多。相反用Notion在本地进行同步时，也有同样的问题，放在Github同步就会快很多。
还有一种可能是由于需要同步的文档中的新图片数量太多，所以每次都是新增上传图片到CDN，会导致整体的流程变慢甚至失败。因为Elog会检测图片在CDN是否已经上传过，可以多试几次。
由于Notion的API在大部分情况下都很慢，甚至会下载文档失败。这是官方的问题，可以选择降低Notion下载文档时的并发数（默认为3）。在Elog配置文件中设置write.notion.limit=1，降低文档下载并发数，也可多试几次。
同步时报超时错误
- 下载文档超时
- 下载图片超时
解决办法
默认超时时间为60s，如果经常超时，可配置环境变量process.env.REQUEST_TIMEOUT，增加请求超时时间。
本地同步时，在.elog.env文件新增REQUEST_TIMEOUT=900000，设置更大的超时时间
在CI/CD中，可在自动化平台注入同样的环境变量即可
如果遇到图片下载失败，可升级到Elog最新版@elog/cli@0.7.2及以上版本，Elog会在上次同步时某文章存在图片下载失败时，第二次同步会重新尝试同步该文章
Elog主要功能是批量导出
Elog在大部分场景下都只是一个批量导出markdown工具，不涉及部署、数据库等功能。
自动化部署、博客平台的路由配置、自定义属性等功能，都是需要各种软件/脚本辅助完成。
不可否认，配置Elog，特别是一定的复杂场景，确实需要一定的代码基础知识，但Elog的其中一个目标也是尽可能地提供开箱即用的配置支持，降低配置的复杂度。
在Elog还没进化到这种程度之前，还是需要大家尽量熟悉Elog使用文档。