如何使用Gatsby和Contentful实现离线开发？

云原生阿岚

2026-8-1

解决Gatsby + Contentful离线开发失败的问题

核心原因

GATSBY_CONTENTFUL_OFFLINE=true 标志的作用是让插件读取本地缓存的Contentful数据，但前提是你已经在线成功运行过一次gatsby develop或gatsby build——插件会将Contentful内容缓存到本地.cache目录。如果没有预先在线缓存数据，离线启动时插件找不到本地缓存，就会尝试请求Contentful的CDN，从而触发域名解析失败的报错。

可行解决方案

1. 先在线完成数据缓存

确保网络正常，执行一次在线开发或构建命令，让插件下载Contentful数据到本地：
```
gatsby develop
```
或者
```
gatsby build
```

完成后再离线执行带标志的命令：

GATSBY_CONTENTFUL_OFFLINE=true gatsby develop

2. 检查缓存目录完整性

确认项目根目录下的.cache目录存在，且包含gatsby-source-contentful相关的缓存文件。如果缓存被清理过，需要重新在线获取一次数据。
若需要频繁离线开发，可以手动备份.cache/gatsby-source-contentful目录，离线时恢复该目录即可。

3. 显式配置插件缓存策略

在gatsby-config.js中给gatsby-source-contentful插件添加缓存配置，确保持久化缓存生效：

module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-contentful`,
      options: {
        spaceId: `你的spaceId`,
        accessToken: `你的accessToken`,
        // 启用持久化缓存，默认已开启，显式声明可避免意外配置覆盖
        persistCache: true,
      },
    },
  ],
}