add-cli-option

添加新的命令行选项

了解如何将硬编码的命令行标志转换为正规的 AnyRemotionOption，或添加全新的选项。

1. 创建选项定义

创建 packages/renderer/src/options/<name>.tsx：

import type {AnyRemotionOption} from './option';

let myValue = false; // module-level default state

const cliFlag = 'my-flag' as const;

export const myFlagOption = {
  name: 'Human-readable Name',
  cliFlag,
  id: cliFlag,
  description: () => <>Description shown in docs.</>,
  ssrName: null, // or 'myFlag' if used in SSR APIs
  docLink: 'https://www.remotion.dev/docs/options/my-flag',
  type: false as boolean, // TypeScript type witness; defaults are resolved in getValue
  getValue: ({commandLine}) => {
    if (commandLine[cliFlag] !== undefined) {
      return {value: commandLine[cliFlag] as boolean, source: 'cli'};
    }
    return {value: myValue, source: 'config'};
  },
  setConfig(value) {
    myValue = value;
  },
} satisfies AnyRemotionOption<boolean>;

AnyRemotionOption<T> 中的类型和 type: <value> as T 决定选项的值类型。可使用 boolean、string | null、number | null 等。

id 必须唯一，且只能包含小写字母、数字和连字符。它决定 /docs/options/<id> 页面和 <Options id="..." /> 的值。通常它与 cliFlag 一致，但共享标志可以使用不同的选项 ID。

将 docLink 设置为 https://www.remotion.dev/docs/options/<id>。

对于取反标志（例如 --disable-ask-ai → askAIEnabled = false），在 getValue 中处理取反逻辑。

2. 在选项索引中注册

packages/renderer/src/options/index.tsx：

• 添加导入（在导入块中按字母顺序排列）
• 将选项添加到 allOptions 对象中

这样，该选项就能在整个代码库中通过 BrowserSafeApis.options.myFlagOption 使用。

3. 更新 CLI 解析后的标志

packages/cli/src/parsed-cli.ts：

• 对于布尔标志，将 BrowserSafeApis.options.myFlagOption.cliFlag 添加到 BooleanFlags 数组中
• 对于非布尔标志，无需在此添加条目（minimist 会自动将它们作为字符串或数字处理）

packages/cli/src/parse-command-line.ts：

• 将其添加到解构的 BrowserSafeApis.options 中
• 在 CommandLineOptions 类型中，添加：[myFlagOption.cliFlag]: TypeOfOption<typeof myFlagOption>;

4. 在需要的地方使用选项

不要直接读取 parsedCli['my-flag']，而应通过以下方式解析：

const myFlag = myFlagOption.getValue({commandLine: parsedCli}).value;

对于 Studio 选项，通常在 packages/cli/src/studio.ts 中处理；对于渲染选项，则在相关的渲染命令文件中处理。

如果 Studio 使用此选项，请在接入前完整阅读 ../studio-config-option-lifecycle/SKILL.md。将所有 Studio 使用方中的选项归类为启动时固定或可重新加载；不允许混合行为。如果任何使用方要求启动时固定，则将启动时快照传递给所有使用方。

5. 添加到 Config

packages/cli/src/config/index.ts：

• 将其添加到解构的 BrowserSafeApis.options 中
• 将 setter 签名添加到 FlatConfig 类型（位于 RemotionConfigObject 全局接口或 FlatConfig 交叉类型中）
• 将实现添加到 Config 对象：setMyFlagEnabled: myFlagOption.setConfig

6. 更新文档——重要，切勿跳过此步骤

此步骤为必做项。 每个新增选项都必须更新文档，使用 <Options id="..." />，以便自动从选项定义中获取描述（单一事实来源）。如果要转换现有的硬编码标志，请用 <Options> 组件替换手写描述。

CLI 命令页面（检查所有适用项：cli/render.mdx、lambda/cli/render.mdx、cloudrun/cli/render.mdx、cli/benchmark.mdx）：

• 添加或更新 ### \--my-flag`` 小节
• 使用 <Options id="my-flag" /> 作为描述正文（无需导入，它是全局可用的）
• id 必须与选项的 id 值一致

CLI 帮助元数据：在每个受支持命令的选项列表中添加该标志，位置为 packages/cli/src/print-help.ts、packages/lambda/src/cli/help.ts 或 packages/cloudrun/src/cli/help.ts。生成的选项页面会使用帮助条目的 optionIds 列出支持的命令；请确保共享标志对应正确的选项 ID。

API 页面：在各自的标题下记录每个公开参数，以便生成的页面可以链接到这些内容。

packages/docs/docs/config.mdx：

• 添加或更新 ## \setMyFlagEnabled()`` 小节，其中包含：
  • 用于描述的 <Options id="my-flag" />
  • 一个 twoslash 配置示例
  • 指向 /docs/options/<id> 的链接，并注明 CLI 标志优先级更高

请遵循附近条目的模式（例如 setAskAIEnabled、setEnableCrossSiteIsolation）。

生成的选项参考文档：使用以下命令生成 packages/docs/docs/options/<id>.mdx 和选项索引。请修改选项定义及 API／配置文档，不要修改生成的 MDX。选项页面会自动添加到侧边栏。

7. 构建并验证

# From the repository root
bun run build
cd packages/docs
bun run generate-option-docs
bun run render-cards
bun run check-option-docs

验证 /docs/options/<id> 是否包含描述、支持的命令以及相关的 API／配置链接。提交生成的页面和索引、文章目录（packages/docs/src/data/articles.ts）以及新的社交预览卡片。

参考文件

• 选项类型定义：packages/renderer/src/options/option.ts
• 可参考的示例：packages/renderer/src/options/ask-ai.tsx（布尔值，仅限 studio）
• 选项索引：packages/renderer/src/options/index.tsx
• CLI 标志注册：packages/cli/src/parsed-cli.ts
• CLI 类型定义：packages/cli/src/parse-command-line.ts
• 配置注册：packages/cli/src/config/index.ts