Goldie配置详解goldie.config.ts逐字段拆解场景、主题、边框字体与多语言【免费下载链接】goldie✨ agentic app store previews and screenshots项目地址: https://gitcode.com/gh_mirrors/gol/goldieGoldie 配置详解Goldie 是一款面向 iOS App 的App Store 截图与预览视频生成工具它的几乎所有行为都由一个文件决定——goldie.config.ts。本文带你逐字段读懂这份 Goldie 配置文件从设备与多语言设置到主题背景、边框bezel样式、内置字体再到截图场景与预览视频的定义看完即可独立写出一份完整可运行的配置。官方提供的示例配置模板 goldie.config.example.ts 带有很全的注释建议对照本文一起看。一、配置文件总览一张表看懂字段分工Goldie 配置的完整类型定义在 src/config.ts 中顶层字段只有 8 个按职责可分为四类字段作用一句话说明appRoot/appPath/bundleId定位 App告诉 Goldie 你的工程、Release 产物和包名在哪里devices/locales/appearance环境与语言选设备尺寸、生成哪些语言版本、浅色还是深色模式frame/theme/store视觉设计边框样式、背景与字体、商店页展示信息scenes内容编排每张截图、每段预览视频的完整定义一个容易踩坑的细节配置里所有相对路径都以配置文件所在目录为基准解析输出目录out/也会创建在配置文件旁边见 loadConfig 的实现。想让配置文件放在 App 仓库里、Goldie 从别处运行可以设置环境变量GOLDIE_CONFIG指向它。二、设备与多语言devices、locales、appearance这三个字段决定了“素材要生成几套、什么规格”。devices目前内置的键来自 src/specs.ts如iphone-6.9对应 iPhone 17 Pro Max 模拟器。它会同时约束截图尺寸1320 × 2868和预览视频尺寸886 × 1920这些数值都按 Apple 上传规范写死在specs.ts里。locales语言列表例如[en-US]。配置中所有文案字段headline、subhead、商店副标题等都是按语言为 key 的字典所以多语言支持几乎是零成本的——多写一个 keyout/下就会多出一个对应语言目录。appearancelight或dark统一控制所有截图时模拟器的系统外观。 想为日文商店生成一套素材在locales里加ja-JP然后给每条headline/subhead补上日语文案即可渲染管线会自动为每个语言各输出一遍。三、边框frame三种内置配色或自定义机身frame决定截图里的 iPhone 机身外观语法上只有两种写法内置变体{ variant: 17-pro-blue }。可选值定义在 FRAME_VARIANTS17-pro-silver、17-pro-blue、17-pro-orange素材就在仓库的assets/目录里三种变体共用同一套屏幕开孔几何数据见 src/frame.ts。自定义图片{ image: path/to/bezel.png }一张带透明屏幕开孔的 PNG路径相对配置文件。注意自定义图意味着要重新测量几何参数日常使用建议优先选内置变体。配色小技巧选与背景形成对比的机身颜色。浅蓝背景配银色机身最干净想要更抢眼就用蓝色或橙色机身。如果只想展示“裸屏”而完全不要边框用theme.screenOnly: true即可Goldie 会给屏幕加一层柔和投影。四、主题theme背景、文字颜色与字体theme是视觉主战场字段完整清单见 Theme 类型定义。1. 背景background它接受任意 CSS 背景值。推荐柔和的品牌色渐变示例配置用的就是一段浅蓝linear-gradient在商店缩略图尺寸下最好看。特殊值transparent会导出带透明通道的 PNG适合二次合成但不能直接上传。2. 文字颜色headlineColor/subheadColor必须与背景保持足够对比度。若你在 Studio 里把背景改成深色Goldie 会自动切换为浅色文字避免“黑底黑字”。3. 字体fontFamily这是一条标准 CSS 字体栈。除系统字体外Goldie 内置了 5 款字体文件位于assets/fonts/注册逻辑见 src/fonts.ts字体风格适合场景Merriweather衬线杂志感、品牌叙事DM Mono等宽开发者工具、极客风Lato / DM Sans / Montserrat无衬线通用、现代、标题感强只需把字体名写在字体栈最前面如Montserrat浏览器预览和导出的 PNG 会保持一致的字形。4. 比例与版式copyHeightRatio文案区占截图高度的比例示例为 0.24deviceWidthRatio机身占截图宽度的比例示例为 0.84template/layout控制整排截图的版式节奏下一节展开讲。五、版式节奏template与layout5 套内置模板 11 种布局theme.template决定每张截图依次使用哪种构图就像给整排截图定一个“节拍”。完整实现见 src/layouts.ts内置模板与自定义序列的对照表整理如下模板版式序列按截图顺序循环应用editorialpanorama → hero → offset → minimal → tiltshowcasehero → tilt → duo → tilt-right → minimalmagazineoffset → copy-below → tilt-right → hero → minimalstoryboardpanorama-duo → copy-below → hero → minimal → tiltdynamictilt → duo-tilt → panorama → minimal → tilt-right也可以直接写一个布局键数组如[panorama, hero, tilt, minimal]序列不够长会自动循环。每张截图还有自己的优先级规则scenes[].layout单张覆盖template中对应项 theme.layout 默认classic11 种布局键中duo、duo-tilt、panorama-duo属于“双屏版式”需要借用下一张截图的画面作为第二块屏可用secondScene指定panorama系列则横跨 2 个商店格位。新手建议先用editorial模板起步效果均衡。六、场景scenes截图场景与预览场景scenes数组按商店页顺序排列有两种元素。截图场景kind: screenshot字段说明id场景唯一标识用于排序和覆盖flowargent 流程名Goldie 会在其最后一步后截图默认从appRoot/.argent/flows查找headline/subhead按语言为 key 的主/副标题文案background仅覆盖本张的背景可选layout仅覆盖本张的版式可选secondScene双屏版式要借用的第二张截图可选decorations仅本张的徽章或图片装饰可选文案建议官方参考 skills/goldie/references/config.md主标题 2~5 个词、讲用户得到的价值而非界面名称写 “Find anything, fast” 而不是 “Search screen”副标题用一句话扩展主标题没有把握就省略。预览场景kind: previewApple 要求 App 预览是纯屏幕录屏不能有边框和字幕因此 Goldie 把预览拆成若干segments每段独立绑定一个 flow、单独录制最后按顺序拼接实现见 PreviewScene 定义segments[].holdSeconds该段结束后多停留几秒总时长必须落在15~30 秒之间PREVIEW 约束可选audio字段指定背景音乐缺省时写入静音音轨。分段录制的好处是某一步流程坏了只需重录那一段不用重录整条“故事线”。七、商店信息store让预览更接近真实上架效果store字段本身不参与截图渲染而是供 Studio 渲染一个仿真商店页帮你判断标题在画廊尺寸下是否还清晰易读。字段包括name、subtitle按语言注意 Apple 的 30 字符上限、developer、category、rating、ratingCount、ageRating、price和description定义见 StoreListing 类型。其中rating等仅起装饰作用不影响上传素材。八、从配置到成品输出与校验配置写好后执行goldie all会完成截图、排版、渲染与校验全流程产物落在out/下、按语言分目录素材规格位置6.9 截图1320 × 2868 PNG无透明通道out/screenshots/6.9/locale/6.9 预览886 × 1920 H.264、30fps、15~30 秒out/previews/6.9/locale/goldie verify会用sips和ffprobe逐文件核对上述规格任何不符都会报错帮你避免上传 App Store Connect 时才发现问题。常见问题速查改了配置没生效确认GOLDIE_CONFIG环境变量没有指向旧文件且路径相对的是配置文件目录。报 “Unknown frame variant / Unknown layout”变体与布局键都是封闭枚举可用值见 FRAME_VARIANTS 与 LAYOUT_KEYS报错信息会列出全部合法值。文案颜色在深色背景上看不清Studio 改背景时会自动换浅色文字手写配置时请自行保证headlineColor与background的对比度。想换配色/排版后 CLI 输出保持一致在 Studio 中做的修改会保存到配置文件旁的goldie.design.jsonCLI 运行时同样生效见 DesignOverrides 说明。 小结goldie.config.ts就是一个“声明式商店素材工厂”——用devices/locales定规格frame/theme定外观scenes定内容。把它和 示例模板 对照填写配合goldie doctor自检就能快速产出符合 Apple 规范的截图与预览视频。【免费下载链接】goldie✨ agentic app store previews and screenshots项目地址: https://gitcode.com/gh_mirrors/gol/goldie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考