Apollo Client 3.0迁移时未知自定义标量问题求助

错误原因 #

这个错误说明Apollo Client无法在你的GraphQL Schema中找到对应名称的自定义标量，常见诱因包括：

• 配置的标量名称与Schema中定义的大小写/拼写完全不一致
• Schema文件未被Apollo插件正确加载（路径配置错误或文件缺失）
• mapScalar配置放置层级错误（Apollo 3.x要求放在具体的service块内）
• 构建缓存残留旧配置导致识别异常

解决步骤 #

1. 核对Schema中的标量定义 #

打开你的GraphQL Schema文件（通常为.graphqls或.graphql格式），确认自定义标量的名称与mapScalar的第一个参数完全匹配，包括大小写。比如Schema中如果定义的是：

scalar DATE
scalar CURRENCY

那配置里的mapScalar("Date", ...)就会匹配失败，必须改为mapScalar("DATE", ...)。

2. 确认Schema文件被正确加载 #

检查build.gradle.kts中的Apollo配置，确保指定了正确的Schema路径和源目录，示例配置：

apollo {
    service("yourServiceName") {
        // 指定GraphQL文件所在目录
        sourceFolder.set("src/main/graphql")
        // 指定Schema文件路径
        schemaFile.set(file("src/main/graphql/schema.graphqls"))
    }
}

确保所有包含自定义标量定义的Schema文件都在指定目录下，未被项目忽略。

3. 修正mapScalar的配置层级 #

Apollo 3.x要求mapScalar必须放在对应的service块内部，不能直接放在apollo根块下。正确的配置结构：

apollo {
    service("yourServiceName") {
        // 其他配置（如sourceFolder、schemaFile）
        mapScalar("Date", "java.time.LocalDate")
        mapScalar("Currency", "java.util.Currency")
        mapScalar("Year", "java.time.Year")
        mapScalar("Month", "java.time.Month")
        mapScalar("Percentage", "kotlin.String")
        mapScalar("MediaType", "kotlin.String")
        mapScalar("Base64", "kotlin.String")
        mapScalar("JSON", "kotlin.String")
    }
}

4. 清理缓存并重新构建 #

执行以下命令清除构建缓存，避免旧配置残留影响：

./gradlew clean build

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