Sanity 项目中 Live Mode 视角初始化问题的分析与解决

在 Sanity 内容管理系统的可视化编辑功能中，Live Mode 是一个关键特性，它允许开发者在预览模式下实时查看内容变更。然而，近期发现了一个关于视角(perspective)初始化的技术问题，本文将深入分析该问题的成因及解决方案。

问题背景

Sanity 的客户端配置支持三种视角模式：

1. 'drafts' - 仅显示草稿内容
2. 'published' - 仅显示已发布内容
3. 'previewDrafts' - 混合显示已发布内容和草稿内容

在实现 Live Mode 时，代码中硬编码将初始视角设置为'drafts'，而忽略了客户端配置中可能指定的其他视角模式。这导致了一个关键问题：当页面是发布版本的一部分时，系统会错误地加载草稿版本（可能不存在），直到接收到正确的视角通知后才更新。

技术细节分析

问题的核心在于 enableLiveMode.ts 文件中的初始化逻辑：

// 原问题代码
const {projectId, dataset} = client.config()
const $perspective = atom<Exclude<ClientPerspective, 'raw'>>('drafts')

这段代码直接从客户端配置中提取了 projectId 和 dataset，却忽略了同样重要的 perspective 参数。正确的实现应该考虑客户端配置中的 perspective 参数，并提供一个合理的默认值：

// 修正后的代码
const {projectId, dataset, perspective} = client.config()
const $perspective = atom<Exclude<ClientPerspective, 'raw'>>(perspective ?? 'drafts')

影响范围

这个问题主要影响以下场景：

1. 使用发布工作流的项目
2. 依赖正确初始视角的预览功能
3. 需要精确控制内容显示状态的应用程序

解决方案实现

在实际应用中，开发者可以通过两种方式确保正确的视角初始化：

1. 客户端配置方式： 在创建客户端实例时明确指定 perspective 参数：

const client = createClient({
  projectId: 'your-project-id',
  dataset: 'production',
  perspective: 'previewDrafts' // 或其他需要的视角
})

2. 查询参数方式： 通过 URL 参数传递视角信息，这在预览场景中特别有用：

export const loader = async ({request}: {request: Request}) => {
  const url = new URL(request.url)
  const perspective = url.searchParams.get('sanity-preview-perspective')?.split(',') as
    | ClientPerspective
    | undefined

  return json({
    initial: await loadQuery(query, {}, {perspective}),
  })
}

最佳实践建议

1. 始终在客户端配置中明确指定 perspective 参数
2. 在预览功能实现中，同时使用客户端配置和查询参数两种方式确保视角正确
3. 在 React 组件中，可以通过 useEffect 监听 perspective 变化，确保UI及时更新
4. 对于关键业务场景，建议添加 perspective 的日志记录，便于问题排查

总结

Sanity 项目的 Live Mode 视角初始化问题展示了配置管理在复杂系统中的重要性。通过正确地从客户端配置中读取 perspective 参数，开发者可以确保系统从一开始就使用正确的视角模式，避免不必要的状态切换和潜在的内容显示问题。这一改进不仅提升了系统的稳定性，也为实现更复杂的发布工作流打下了坚实基础。

对于正在使用 Sanity 可视化编辑功能的开发者，建议及时更新到包含此修复的最新版本，以确保获得最佳的使用体验。