Sanity站点内容预览功能异常：按文档配置后上下文菜单未显示预览入口

问题核心特征 #

• 已按照开发指引完成配置更新：调整sanity.json、新增resolveProductionUrl.js逻辑文件
• 函数调用链路正常：在文件中添加调试日志后，可在浏览器控制台看到对应输出，证明函数已被触发执行
• 界面渲染异常：内容项的右键上下文菜单中，始终没有出现预期的预览菜单项

高频排查方向 #

• 函数返回值格式校验不通过
  函数被触发不代表返回值满足菜单渲染要求，Sanity会对返回值做合法性校验，只有通过校验的返回结果才会触发菜单项渲染：
  • 必须返回带完整协议头的绝对URL字符串，不能返回相对路径、空值、对象类型等非合规内容
  • 常见错误：拼接返回的地址缺少https://前缀、slug取值为空导致返回值为无效路径
  • 典型错误示例：return "/posts/" + slug.current 这种相对路径的返回值会被直接拦截，不会触发菜单渲染
• sanity.json配置路径匹配错误
  配置项中的文件路径必须和项目实际的文件存放路径完全一致：
  • 检查productionUrl节点下的resolve属性值，不要出现层级写反、缺少文件后缀的问题
  • 确认配置写在根层级的productionUrl节点下，没有误嵌套到其他插件的配置块中
• 本地缓存未刷新
  Sanity Studio会对配置和功能逻辑做本地缓存，即便逻辑已被触发，缓存的旧菜单渲染逻辑也可能不加载预览入口：
  • 对Studio页面执行强制刷新（Windows端Ctrl+Shift+R，Mac端Cmd+Shift+R）
  • 停止本地Studio服务，删除项目下的node_modules/.cache缓存目录后，重新启动服务
• 对应内容类型的预览权限被覆盖
  检查当前测试的内容项对应的schema配置，确认没有通过自定义逻辑手动禁用预览入口，部分自定义schema的默认配置会覆盖全局的预览渲染规则

快速定位小技巧 #

在resolveProductionUrl.js的return语句前，将最终待返回的URL赋值到全局对象上，写法为window.__preview_test_url = 最终拼接完成的地址。打开浏览器控制台查看该值：如果取值为空、格式不符合URL规范，直接修正返回逻辑后，预览菜单项即可正常渲染。

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