Nuxt Content远程仓库连接报错：incorrect header check

问题背景 #

我按照Nuxt Content官方文档配置远程仓库，代码如下：

export default defineContentConfig({
    collections: {
        index: defineCollection({
            type: "page",
            source: {
                repository: "https://github.com/xxx/blog",
                include: "index.yml",
            },
            schema: z.object({
                hero: z.object({
                    // 省略后续schema内容
                })
            })
        })
    }
})

已确认index.yml文件位于仓库根目录，但启动项目时反复抛出incorrect header check错误，报错栈如下：

Nuxt 4.2.1 (with Nitro 2.12.9, Vite 7.2.4 and Vue 3.5.24)                                                                                                           nuxi 10:43:09 AM
                                                                                                                                                                         10:43:09 AM
  Γ₧£ Local:    http://localhost:3000/
  Γ₧£ Network:  use --host to expose

                                                                                                                                                                         10:43:10 AM
                                                                                                                                                                         10:43:10 AM
                                                                                                                                                                         10:43:10 AM
  Γ₧£ DevTools: press Shift + Alt + D in the browser (v3.1.0)                                                                                                              10:43:10 AM


 ERROR  incorrect header check                                                                                                                                           10:43:10 AM

    at genericNodeError (node:internal/errors:983:15)
    at wrappedFn (node:internal/errors:537:14)
    at Zlib.zlibOnError [as onerror] (node:zlib:190:17)
    at Zlib.callbackTrampoline (node:internal/async_hooks:130:17)

解决方案 #

• 补全Auth Token配置
  如果仓库是私有库，必须在source中添加authToken字段，使用具备仓库读取权限的GitHub个人访问令牌。即使是公开仓库，配置令牌也能避免请求频率限制引发的异常：

  source: {
      repository: "https://github.com/xxx/blog",
      include: "index.yml",
      authToken: "你的GitHub个人访问令牌"
  }
  

• 校验仓库地址格式
  确保仓库地址为标准HTTPS格式，不要附加.git后缀，直接使用https://github.com/xxx/blog即可。

• 清理缓存后重启
  Nuxt Content可能缓存了错误的远程资源，执行以下命令清理缓存再启动项目：

  npx nuxi clean
  npm run dev
  

• 切换兼容的Node.js版本
  报错涉及Zlib模块，部分Node.js版本与Nuxt 4.x存在兼容性问题，建议使用Node.js 20.x LTS版本，避免版本过低或过高导致底层模块异常。

• 检查文件编码与格式
  确认index.yml使用UTF-8编码，避免特殊字符或格式错误引发解析时的压缩/解压问题。可以尝试创建一个干净的测试文件验证。

内容的提问来源于stack exchange，提问作者Riza Khan