Netlify Graph无法保存Spotify API自定义查询 生成Handler报错

故障表现 #

• 为Spotify API编写的自定义GraphQL查询可在GraphQL Playground中正常运行、返回符合预期的结果，但执行保存查询、创建Handler操作时触发异常，无法生成对应的Netlify Function处理函数。

终端报错信息 #

生成Handler时终端输出如下内容：

Handling Netlify Graph: Generate handler as Netlify function ...
 »   Warning: Operation [object Object] not found in graphql, found: dac9c498-f1fc-4cac-ae1b-38a134c116ab}
 »   Warning: No handler was generated for operationId [object Object]
 »   Warning: No files generated for operation id: [object Object]
Finished handling Netlify Graph: Generate handler as Netlify function ...

问题根因 #

报错中反复出现[object Object]格式的operationId，说明CLI在读取已保存查询的操作ID时出现类型解析错误：没有正确获取字符串格式的操作ID，反而读取到了整个操作配置对象，导致无法匹配到已保存的查询记录，最终终止Handler生成流程。

修复操作步骤 #

• 清除本地缓存：删除项目根目录下.netlify/graph文件夹内所有和本次Spotify查询相关的缓存文件，避免旧的错误配置干扰后续流程。
• 规范保存查询：回到Netlify Graph Playground，不要直接在临时查询面板触发Handler生成操作。先点击查询面板上方的Save operation按钮，给查询设置纯英文、无特殊字符和空格的名称（比如SearchTracks），确认保存后能在左侧已保存操作列表看到该条查询。
• 拉取最新配置：回到本地项目根目录，执行netlify graph pull命令拉取最新的Graph配置，拉取完成后检查netlify/graph/operations目录下是否存在对应名称的.graphql文件，确认文件内查询代码和编写的内容一致：

query SearchQuery($search: String!) {
  spotify {
    search(data: {query: $search}, first: 10) {
      tracks {
        id
        name
        album {
          name
          images {
            url
          }
        }
        artists {
          name
        }
      }
    }
  }
}

• 本地生成Handler：不要使用Playground网页端的一键生成Handler按钮，直接在本地终端执行生成命令，指定报错信息里提示已找到的操作UUID即可，命令如下：

netlify graph:handler --id dac9c498-f1fc-4cac-ae1b-38a134c116ab

• 验证生成结果：命令执行完成后，打开项目下netlify/functions目录，即可看到自动生成的对应查询处理函数。

避坑提示 #

新手使用Netlify Graph时尽量不要依赖网页端一键生成Handler的功能，保存查询后先在本地拉取最新配置，再通过本地命令执行Handler生成操作，可避开绝大多数网页端传参类型错误导致的生成失败问题。

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