React Cosmos 中 Vite 项目多脚本路径问题的分析与解决

问题背景

在使用 React Cosmos 进行组件开发时，开发者遇到了一个与 Vite 构建工具相关的错误提示："Internal server error: Multiple script paths found in index.html. Please set vite.mainScriptUrl in your Cosmos config"。这个错误特别之处在于它只会在页面重新加载后出现，而初始加载时却能正常工作。

问题现象

开发者详细描述了问题出现的场景：

1. 使用 React Cosmos 的 canary 或 next 版本时
2. 服务器启动时一切正常
3. 在导航到不同组件后
4. 重新加载页面时
5. 上述错误就会出现

配置分析

从开发者提供的 cosmos 配置文件中，我们可以看到这是一个标准的 Vite 项目配置，包含了常见的设置如静态资源路径、全局样式导入、插件配置等。特别值得注意的是配置中已经正确设置了 vite.configPath 指向项目的 Vite 配置文件。

问题排查

开发者通过版本对比发现：

• 在 6.2.4-canary.b2d1977.0 版本中问题不会出现
• 在 7.0.0-canary.f624342.0 版本中问题会出现

这表明这个问题可能与特定版本相关，可能是新版本引入的某种检查机制导致的。

解决方案探索

在交流过程中，项目维护者建议查看 index.html 文件内容。从开发者提供的 HTML 文件来看，实际上只有一个脚本引用：

<script type="module" src="/src/index.tsx"></script>

这显然不是真正的"多脚本路径"问题。维护者表示在单元测试中同样的 HTML 内容能够正常工作，说明问题可能出在其他方面。

最终解决

开发者最终发现：

1. 将 lazy 配置设置为 true 可能是问题的根源
2. 升级到 7.0.0-beta.2 版本后问题不再出现

相关问题的延伸解决

在讨论过程中，开发者还提出了另一个关于 React Router 状态更新不生效的问题。项目维护者给出了专业建议：使用 Cosmos 的装饰器(Decorators)功能来包装路由提供者，而不是在每个 fixture 中单独包装。这种方法既解决了状态更新问题，又保持了代码的整洁性。

总结

这个案例展示了在 React Cosmos 项目中可能遇到的配置问题及其解决方法。关键点包括：

1. 版本兼容性问题需要特别关注
2. 配置项的细微差别可能导致不同行为
3. 使用装饰器模式可以优雅地解决组件包装问题

对于开发者来说，遇到类似问题时，建议：

1. 检查版本差异
2. 简化配置进行测试
3. 充分利用框架提供的装饰器等高级功能