用途:为 Remotion Studio 的每个配置项明确重载行为。配置文件变化时会被重置并重新执行,但消费者只有在再次读取该配置项时才能观察到新值。需要先检查全部 Studio 消费者,再为整个配置项分配一种生命周期:启动固定(改动值需重建服务器、编译器、监听器、目录映射等已初始化资源)或可重载(浏览器重载或另一个有意的请求边界后,所有消费者都能安全使用新值)。只要有一个消费者必须启动固定,该配置项对所有 Studio 消费者都按启动固定处理,不得实现混合生命周期。不能因为 Config.set*() 状态被更新就推断为可重载。
启动固定值的接线:在调用 startStudio() 前于 packages/cli/src/studio.ts 中解析一次,得到 fixedValue,然后通过 startStudio()、startServer() 和消费者传递该值而非 getter;新增内部参数保持必填,无值有效时用 T | null。启动固定的渲染设置要在 Studio 队列边界捕获进 StudioRenderJobFixedConfig 并传入作业处理器,处理器内不要调用 option.getValue()。常见启动固定消费者包括 Studio 端口、入口点、当前编译器及覆盖、轮询模式、公共目录与监听器、网络绑定、跨站隔离头。
可重载值的接线:用保留 CLI 优先级的 getter 读取,将其作为必填内部回调传入,只在应观察配置变化的边界调用,例如配置文件变更后浏览器重载时生成 Studio HTML;不要提前求值再传递结果。已有 StudioRuntimeConfig 表示的值沿用 getStudioRuntimeConfig()。扩展该导出类型时注意新增必填属性可能造成公开 API 破坏。仅当所有消费者都可重载时使用此模式。
冲突排查:可用 rg -n "myOption|setMyOption|my-cli-flag" packages 搜索所有读取处逐一判断;若消费者并非都支持重载,则在 Studio 启动时捕获一次并传给每个消费者。别名视为同一选项,已废弃 setter 更新多个底层值时按更严格的启动固定处理。
重置与回滚:确保配置重载先重置选项再执行变更文件,使删除 setter 恢复默认;通过 BrowserSafeApis.options 注册并经 Config 暴露的选项由 resetBrowserSafeConfigOptions() 重置,自定义模块状态需在 ConfigInternals.resetConfigOptions() 中显式重置;保留事务式重载,无效配置不得生效。验证:可重载项改动后跨过重载/请求边界确认新值生效;启动固定项捕获初值后改配置状态,确认已初始化消费者仍收到原值;跨消费者确认都拿到同一启动快照;重载时省略曾设置的选项确认恢复默认;可空内部输入确认显式传 null。可运行 bunx turbo run make lint formatting --filter='@remotion/cli' --filter='@remotion/studio-server' 以及 bun test packages/cli/src/test/config-reload.test.ts packages/cli/src/test/config-reset.test.ts。