studio-config-option-lifecycle

Studio 配置选项生命周期

明确每个面向 Studio 的选项的重新加载行为。配置文件发生变化时会重置并重新执行，但只有当使用方代码再次读取该选项时，才能观察到新值。

对整个选项进行分类

检查每个 Studio 使用方，然后为整个选项指定一种生命周期：

• 启动时固定： 更改该值需要重新创建服务器、编译器、监视器、目录映射或其他已初始化资源。
• 可重新加载： 浏览器重新加载后，或在其他明确的请求边界处，每个 Studio 使用方都能安全地使用新值。

如果任何使用方必须在启动时固定，则所有 Studio 使用方都必须将该选项视为启动时固定。不要实现混合生命周期行为。

不要根据 Config.set*() 状态已更新就推断选项可以重新加载。无论现有使用方是否能观察到新状态，重新执行配置都会更新模块状态。

接入启动时固定的值

在调用 startStudio() 之前，于 packages/cli/src/studio.ts 中解析该选项一次：

const fixedValue = option.getValue({commandLine: parsedCli}).value;

await StudioServerInternals.startStudio({
	fixedValue,
});

将值而非 getter 传递给 startStudio()、startServer() 和使用方。新增的内部参数必须保持为必需参数；如果允许缺省，则使用 T | null。

在 Studio 队列边界处，将启动时固定的渲染设置捕获到 StudioRenderJobFixedConfig 中，并将该对象传递给作业处理器。不要在处理器中调用 option.getValue()，因为自 Studio 启动后配置状态可能已经发生变化。

典型的启动时固定使用方包括 Studio 端口、入口点、当前编译器选择及覆盖项、轮询模式、公共目录及其监视器、网络绑定和跨站点隔离标头。

接入可重新加载的值

通过保留 CLI 优先级的 getter 读取可重新加载的选项：

const getValue = () =>
	option.getValue({commandLine: parsedCli}).value;

await StudioServerInternals.startStudio({
	getValue,
});

将 getter 作为必需的内部回调传递，并仅在应观察到配置变化的边界调用它，例如浏览器在 config-file-changed 后重新加载时生成 Studio HTML。不要提前计算 getter 的值再向下传递。

对于已由 StudioRuntimeConfig 表示的值，使用现有的 getStudioRuntimeConfig() 路径。扩展该导出类型时请谨慎：添加必需属性可能会造成公共 API 破坏。对于独立的 HTML 引导值，则通过内部 Studio 服务器层传递专用 getter。

仅当所有 Studio 使用方都支持重新加载时，才使用此模式。典型示例包括 UI 行为和 HTML 引导默认值，只要它们不需要重建已初始化的资源。

解决生命周期冲突

搜索该选项的所有读取位置，并逐一判断：

rg -n "myOption|setMyOption|my-cli-flag" packages

如果并非所有使用方都支持重新加载，则在 Studio 启动时捕获该选项一次，并将同一个值传递给每个使用方。例如，如果当前预览编译器无法更换打包器，则未来的渲染作业也必须保留启动时的打包器选择。

将别名视为同一个选项。如果已弃用的 setter 会更新多个底层值，则所有受影响的 Studio 使用方都必须采用更严格的启动时固定生命周期。

重置与回滚

确保配置重新加载会在执行变更后的文件之前重置该选项，这样删除 setter 就会恢复默认值。通过 BrowserSafeApis.options 注册并直接通过 Config 暴露的选项由 resetBrowserSafeConfigOptions() 重置。对于自定义模块状态，则在 ConfigInternals.resetConfigOptions() 中显式添加重置逻辑。

保留事务式重新加载行为：无效的变更后配置必须保留先前有效的配置。

验证生命周期

使用现有检查或手动工作流验证分类：

• 可重新加载：在首次读取后更改选项，跨越预期的重新加载／请求边界，并确认观察到新值。
• 启动时固定：捕获初始值，更改配置状态，并确认已初始化的使用方仍会收到原始值。
• 跨使用方：当任一 Studio 使用方需要启动快照时，确认每个 Studio 使用方都收到相同的快照。
• 重置：重新加载时省略先前设置的选项，并确认其默认值已恢复。
• 可空内部输入：验证调用点在没有值时会显式传入 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