这里集中回答 LetsGal Studio 使用过程中最常遇到的问题。遇到异常时，先保存项目并查看错误提示；涉及素材、构建或协作时，不要直接删除项目文件来尝试修复。
第一次使用先看
LetsGal Studio 是什么？
LetsGal Studio 是面向 Galgame 和视觉小说的可视化创作工具。它把剧本、角色立绘、场景、声音、分支、变量、演出、游戏界面和构建发布放在同一个项目中管理。
不写代码也可以完成一部常规视觉小说；需要背包、养成、地图、小游戏或特殊界面时，可以通过 TypeScript、React 和 Studio SDK 开发扩展。
不写代码能做到什么？
| 能力 | 可以完成的内容 |
|---|
| 剧本 | 对白、旁白、选项分支、条件判断、变量、章节和 Fragment |
| 角色与场景 | 普通、序列帧、差分、Spine 与 Live2D 立绘，立绘皮肤、距离与位置，多层场景和视差 |
| 演出 | 镜头、粒子、声音、视频、幕布、浮动文字和时间线动画 |
| 游戏界面 | 标题、存读档、设置、历史、鉴赏、对话框、HUD 和剧情面板 |
| 工作流 | 剧本导入与导出、网格动画、实时预览、调试、项目历史、云端分享和多人协作 |
| 发布 | macOS、Windows、Linux，以及测试版 Web 和 Android Debug APK 构建 |
写代码以后还能扩展到什么程度？
程序扩展可以提供 React UI、自定义剧本方法、章节调度策略、设置、存档字段和系统界面，也可以使用 Canvas 或 WebGL 制作小游戏及特殊渲染。
扩展能够读取和控制剧情变量、角色、场景、声音、镜头、存档和界面，因此可以实现背包、好感度、任务、地图选点、日程、战斗面板、解谜和小游戏等系统。扩展入口见扩展是什么。
Studio 的能力边界在哪里？
- 核心定位是视觉小说：常规文字冒险和 2D 演出是内置能力；复杂 3D 世界、物理模拟、大型实时动作游戏不属于内置工作流。
- 可视化 UI 不是网页导入器：它适合用编辑器搭建游戏界面，但不能把任意网站、HTML 包或外部程序一键嵌入。
- 小游戏需要适配或开发：有 React、TypeScript、Canvas 或 WebGL 源码时可以改造成扩展；只有 EXE 或其他引擎成品时，通常需要重写交互层。
- Web 构建仍是测试版：浏览器不支持
ctx.native.node，桌面原生扩展不能直接用于 Web；Web 产物也不提供资源加密。
- Android 构建仍是测试版：目前可以生成 Debug APK，适合设备验证；iOS 尚未开放，正式上架能力不能由 Debug APK 替代。
- Studio 不替代素材工具：图片、立绘、音乐、视频、字体和配音仍需自行制作或合法取得授权。
- 项目历史不备份素材文件：它可以恢复剧本和配置，不能找回已经删除的图片、音频或视频。
- 实时协作有用量上限：单个文件最大 2 GB，每个协作项目默认最多 20 GB，超出的文件不会同步。
我应该选择哪种制作方式？
| 目标 | 推荐方式 |
|---|
| 制作常规 Galgame | 可视化剧本 Block + 内置界面 |
| 修改标题页、菜单或 HUD | 可视化 UI |
| 制作复杂动态界面 | 可视化 UI + TypeScript 控制器 |
| 制作小游戏、Canvas 或 WebGL 内容 | 程序扩展 UI |
| 接入已有网页或外部小游戏 | 取得源码后适配为扩展，不建议直接嵌入成品 |
| 发布浏览器版本 | Web 测试版构建，并避开 Node 原生能力 |
| 多人共同编辑 | 开启实时协作，成员凭邀请码加入 |
安装与工作区
macOS 提示应用“已损坏”，怎么办？
确认安装包来自 LetsGal Studio 官网，然后在终端执行：
xattr -dr com.apple.quarantine "/Applications/LetsGal Studio.app"
有 Linux 版和 Intel 芯片的 Mac 版吗？
有，目前都提供 Beta 版，在官网下载页下载。这两个版本不提供整包自动更新，有新版本时到官网重新下载。
Linux 版导出游戏有什么限制？
- 在 Linux 版 Studio 上可以导出 Linux、Windows 和 Mac 版游戏，其中 Mac 版只生成压缩包。
- Linux 版游戏只能在 Linux 版 Studio 上导出，Windows 和 macOS 上的 Studio 目前不能导出 Linux 版。
详见发布游戏。
新版本的 Windows 更新为什么要管理员授权？
Studio 安装在 Program Files 等受系统保护的位置，或选择了为所有用户安装时，更新需要管理员权限。点击「以管理员身份继续」，在 Windows 弹出的窗口中选择「是」。
不想每次授权，可以从官网下载完整安装包，重新安装到非系统盘。其他更新提示见安装与首次启动。
工作区和项目有什么区别？
工作区是保存多个项目的文件夹，每个项目是其中一个独立子目录。不要把某个具体项目目录再次选成工作区，否则项目列表和文件层级容易混乱。
需要更换工作区时到 Studio 设置中修改。移动项目前先关闭 Studio，再整体移动项目文件夹，不要只移动其中的章节或资源目录。
为什么不能把 Studio 安装目录设为工作区？
安装目录会在应用更新或重新安装时被替换，不适合保存项目。Studio 会阻止选择自身安装目录，避免更新时误删项目；请另选“文档”或其它专门的创作目录。
素材与资源
为什么素材已经在磁盘上，Studio 仍提示缺失？
项目保存的是素材相对路径。在系统文件管理器中移动、重命名或删除文件后，原引用不会自动跟随。
请重新导入文件、恢复原路径，或删除对应引用。可以在资源总览中检查缺失引用及其使用位置。
为什么拖入图片后没有自动出现在剧本里？
导入素材只会把文件加入资源库，或创建角色、场景等实体，不会自动插入剧情 Block。导入后仍需在剧本目标位置添加 Scene、Show Character、Video 等对应 Block。
删除的图片或音频能通过项目历史恢复吗？
不能。项目历史恢复剧本、角色、场景、界面、变量和项目配置，不保存图片、音频、视频等素材文件内容。
素材文件应使用 Time Machine、Windows 文件历史、Git LFS 或其他备份工具保护。详见项目历史。
视频已经导入，为什么预览黑屏？
先确认视频使用受支持的编码。文件扩展名相同不代表内部编码一定兼容；必要时转换为常见的 MP4/H.264 后重新导入。更多检查方法见视频素材常见问题。
Live2D 为什么能导入但不能预览或构建？
Studio 不内置 Live2D Cubism Core。请在 设置 → 第三方授权 → Live2D Cubism 安装本人从官方合法取得的 Cubism SDK for Web；换电脑构建时也需要在新电脑重新安装。详细要求见动态图像与动态立绘。
多个扩展怎样共用道具或图鉴数据？
把静态资料建立为项目数据集合，再分别绑定到扩展声明的数据依赖。数据表属于项目，不会因为卸载某个扩展而删除；扩展开发者可通过 ctx.database访问自己的绑定。
剧本编辑
怎样插入新的 Block？
在空白旁白块按 Tab 打开菜单，再选择对白、场景、声音、条件、变量或演出 Block。连续对白内部也可以按 Tab 调整角色显示名、距离与位置、表情和皮肤。
所有内置 Block 可从Block 总览继续查看。
为什么纯文本行不能直接修改某些参数？
纯文本模式支持直接编辑对白和旁白；复杂 Block 以摘要占位，完整参数在属性检查器中修改。Ren’Py 风格代码编辑器是另一个模式，可把兼容语句转换为 Block；遇到不兼容语法时先修正代码，再切回卡片。
选中对应行后使用属性检查器，或切回卡片视图修改完整参数。详见剧本编辑器与Ren’Py 风格代码编辑器。
导入图片或扫描 PDF 时为什么提示需要 OCR？
剧本导入只会把本地提取出的文字交给文本模型，不会直接把图片或二进制 PDF 发给模型。扫描件没有文字层时，请先使用 OCR 工具转换成可复制文本或带文字层的 PDF，再重新导入。
场景切换时角色或旧画面没有按预期清除，怎么办？
Scene Block 负责切换背景，但复杂换场可能还需要移除角色、销毁场景或使用幕布遮挡多个操作。
规则图素材缺失会导致剧情卡住吗？
不会。规则图为空或加载失败时，场景转场会安全退化为随机溶解。自定义规则图需要作为“规则图”素材导入；也可以直接选择 Studio 提供的内置规则图。
可视化 UI 与小游戏
怎么制作可视化 UI？
可视化 UI 适合制作标题页、菜单、HUD、弹窗、任务面板和简单剧情交互，不需要先写 React 代码。
基本流程：
- 进入“个性化 → 项目设置”。
- 在左侧扩展树中新建或选择一个本地扩展。
- 展开扩展下的“界面”，点击新增并输入界面名称。
- 在设计视图中添加文字、图片、按钮、列表、表单或智能组件。
- 使用右侧检查器调整位置、尺寸、锚点、样式、数据绑定和点击动作。
- 到动画视图配置入场、退场和页面动画。
- 切换到预览视图，实际测试按钮、变量、数据和关闭流程。
只做排版和内置动作时，不需要初始化扩展程序。需要复杂计算、动态生成内容或调用外部服务时，可以再为扩展初始化程序，并通过 TypeScript 控制现有界面。
完整教程见可视化界面编辑器，元素、数据和动画分别见界面元素、界面数据与动作和界面动画。
怎么制作一个标题画面？
最快的方式是修改项目自带的标题画面：
- 进入“个性化 → 项目设置”。
- 在扩展树中展开“默认游戏壳 → 界面”。
- 选择“标题画面”并进入编辑器。第一次修改时，Studio 会为当前项目创建可编辑副本。
- 更换背景图、Logo 和标题文字，再调整按钮的位置、字体、颜色和动画。
- 切换到预览视图，依次测试新游戏、继续、设置、鉴赏和退出。
- 回到剧本，在入口章节需要显示标题的位置插入一个“显示界面”Block，并选择标题画面。
创建或修改可视化界面，只是保存了这份界面本身。要让它在剧本运行到某个位置时真正出现，还需要插入“显示界面”Block。
在剧本中显示标题画面
- 打开项目的入口章节。
- 在开头的空白旁白块按 Tab。
- 选择“显示界面”。
- 在界面选择器中选择“系统插槽 → 标题画面”；如果没有使用系统插槽，也可以选择刚才创建的具体可视化界面。
- 标题画面通常设为“等待界面关闭 + 始终在顶层”，让剧本等待玩家点击开始、继续或其他入口。
推荐选择“系统插槽 → 标题画面”。这样以后更换标题画面的绑定目标，剧本中的 Block 会自动跟随，不需要重新选择界面。完整参数见显示 UI。
标题画面常用按钮及对应动作：
| 按钮 | 点击动作 |
|---|
| 开始游戏 | 开始新游戏 |
| 继续游戏 | 继续最近存档 |
| 读取存档 | 打开读档 |
| 设置 | 打开设置 |
| 历史记录 | 打开历史记录 |
| 鉴赏 | 打开鉴赏 |
| 退出 | 退出游戏 |
- 新建一个本地扩展，并在扩展下创建可视化界面。
- 按项目画布尺寸添加铺满画面的背景、Logo、按钮和装饰元素。
- 为按钮配置上表中的系统动作。
- 到“个性化 → 项目设置 → 游戏系统”。
- 把“标题画面”插槽绑定到新建的界面。
- 回到入口章节，插入“显示界面”Block，并选择“系统插槽 → 标题画面”。
- 从项目入口运行预览，检查首次启动、已有存档和返回标题三种状态。
优先使用“打开设置”“打开读档”等系统动作，不要让按钮写死某一份具体界面。以后替换设置或存读档界面时，标题画面会自动跟随新的系统绑定。
“恢复原始界面”会丢弃当前项目对默认标题画面的修改。进行大改前，可以把标题画面复制到自己的本地扩展中保留版本。
Studio 能直接插入外部制作的小游戏吗？
Studio 目前没有把任意 HTML 网页、独立 EXE 或其他引擎导出包直接嵌入剧情的通用导入按钮。外部小游戏能否使用，取决于你是否拥有源码，以及它能否适配 Studio 的运行环境。
- 已有 React、TypeScript、Canvas 或 WebGL 源码：可以改造成程序扩展 UI，通常是最合适的接入方式。
- 只有网页构建产物：不能保证直接嵌入；建议取得源码后改造成扩展，而不是依赖
iframe 或外部网页。
- 只有独立可执行程序：不适合作为游戏内 UI，也无法用于 Web 构建。桌面端即使通过原生能力启动外部程序，也会带来打包、权限、存档和跨平台问题。
- 来自其他游戏引擎的工程：通常需要重写交互层，或者把核心规则和素材迁移到 Studio 扩展中。
接入第三方小游戏前，还要确认代码、素材、字体、音乐和第三方库的许可证允许随作品分发。
能不能直接在 Studio 里开发小游戏？
可以。推荐使用“程序扩展 + 程序 UI”，通过 React、Canvas 或 WebGL 实现小游戏画面和交互，再使用 Studio SDK 连接剧情。
典型结构是：
- 新建本地扩展并初始化程序。
- 在扩展的
render() 中返回小游戏的 React 组件。
- 使用
ctx.variables、扩展存档 Schema 或项目变量保存分数、结果和进度。
- 使用角色、场景、音频和素材 API 读取项目内容。
- 在剧本中插入“显示 UI”Block，选择该扩展的程序 UI。
- 把界面设为“等待界面关闭 + 始终在顶层”，让剧情等待小游戏结束。
- 小游戏结束时写入结果并关闭 UI，剧本再根据变量进入成功或失败分支。
如果小游戏主要是按钮、文字、图片和简单状态切换，可以先用可视化 UI 搭建，再通过 ctx.visualUI补充逻辑；需要实时循环、碰撞、Canvas、WebGL 或复杂动画时，直接使用程序 UI 更合适。
开发入口见扩展是什么和开发流程。剧本打开方式见显示 UI，存档数据见存档 Schema。
小游戏如果需要同时发布到 Web，请使用浏览器兼容 API，不要依赖 ctx.native.node。桌面原生模块在 Web 构建中不可用。
预览与调试
预览为什么停在某个位置不再继续？
先查看调试面板的当前 OP 和日志。常见原因包括：
- Wait Block 正在等待时间或玩家点击；
- 分支正在等待玩家选择；
- 输入界面或自定义 UI 尚未关闭；
- 引用的 Fragment、变量、素材或扩展方法无效；
- 自定义扩展的异步方法没有结束。
可以从当前章节或指定位置重新运行，并参考运行与调试定位具体操作。
为什么预览清晰，但换一台设备后画面性能不同？
内部渲染倍率、作品目标帧率和作品特效质量都会影响 GPU 开销。高倍率、高帧率和高特效质量组合在低性能设备上可能不稳定。
到画面渲染设置检查渲染精度、倍率上限、图片采样、作品目标帧率和特效质量，并在目标设备上实际测试。
打包与 Web
构建为什么因为缺失素材而中断？
构建会扫描所有有效引用。只要剧本、角色、场景、界面或扩展配置仍引用不存在的文件，就不会生成一个内容残缺的游戏包。
根据错误信息列出的引用位置重新导入素材、恢复路径或删除引用，再重新构建。详见缺失素材会中断打包。
Web 构建完成后应该上传哪些文件？
保持以下同级目录结构整体部署：
dist/
├── web/
└── assets/
web 是页面，assets 是游戏资源。使用默认 ../assets/ 时不需要提前填写域名；只有把素材独立部署到 CDN 时，才需要填写完整资源地址并正确配置跨域。
完整说明见Web 测试版。
为什么不能直接双击 Web 构建里的 HTML 试玩？
浏览器通过 file:// 打开页面时会限制模块和资源请求。请使用构建完成后的“本地试玩 Web”，或通过本地 HTTP 服务访问 dist/web，不要直接双击 HTML 文件。
桌面版可用的扩展为什么在 Web 版失效？
浏览器不能调用 Node 原生模块。使用 ctx.native.node 的扩展只适用于桌面环境，不会在 Web 构建中运行。需要同时发布 Web 版时，应提供浏览器兼容实现或避免依赖原生能力。
当前构建产物会加密游戏资源吗？
桌面端可以。在构建方案的「PC 桌面端」设置中开启「加密游戏内容」，Studio 会把剧本、素材和扩展运行文件封装进 .lgpak。「默认」方案不加密，正式发布请使用开启加密的方案（老项目升级后会自动生成「正式发布」方案，见构建方案）。Web 构建仍输出浏览器可读取的明文资源目录。
加密用于提高直接提取内容的成本，不等同于不可破解的 DRM。具体设置和限制见桌面端内容加密。
导出的游戏为什么按 F12 没反应？
导出的游戏只有在构建方案开启「调试模式」时才能打开开发者工具，不加密的游戏也一样。需要自查时，在测试用的方案里打开调试模式并重新构建；正式发布的方案请保持关闭。也可以用 Studio 的「模拟游玩」，它始终可以按 F12。详见调试模式。
项目历史与协作
项目历史多久创建一次快照？
默认每 2 分钟检查一次，可以在“设置 → 系统”调整为 1–120 分钟。只有项目内容发生变化时才创建自动快照；删除、重命名、排序以及打开或关闭项目还可能创建里程碑。
没有本地项目能加入协作吗？
可以。在首页点击「加入协作」，输入发起者给的 8 位邀请码。素材下载完成前，部分图片和声音会暂时显示为缺失。
协作时为什么不能改章节名或删除章节？
有其他成员正在写这一章的某一句。故事树会提示是谁在写，等对方离开这一章就可以改名或删除。
为什么协作成员没有收到新增素材？
素材会自动同步，大文件需要一点时间，可以在协作窗口查看传输进度。单个文件最大 2 GB，每个协作项目默认最多 20 GB。详见实时协作。
扩展与更新
分享项目后，对方还需要安装相同扩展吗？
项目启用扩展后，运行所需的项目发行物会跟随项目保存。正常复制或云端分享完整项目时，对方不需要另行安装原扩展；扩展源码不会包含在项目发行物中。
如果只是单独复制章节，扩展、素材或配置仍可能缺失。
为什么调用扩展方法时找不到某个方法？
确认扩展已经加入并启用。部分扩展方法还会根据项目设置按需显示；关闭对应能力后，它不会出现在新建候选中，但剧本里已经使用的方法仍会保留并正常执行。
Stable 和 Beta 更新通道有什么区别？
Stable 适合日常创作，Beta 用于提前体验尚未完全稳定的功能。切换通道不会修改项目内容，但 Beta 版本创建或升级的数据不一定适合旧版 Studio 打开。
更新设置和差分下载说明见Studio 设置 · 版本更新。
仍然无法解决
反馈问题时，建议同时准备：
- Studio 完整版本号和更新通道；
- 操作系统版本；
- 能稳定复现问题的步骤；
- 报错文字、构建日志或调试日志；
- 不包含敏感内容的截图；
- 问题是否只在某个项目、某个平台或某种构建目标出现。
先用项目副本复现问题。不要直接发送包含未公开剧本、账号令牌或商业素材的完整项目。
升级与功能常见问题
欢迎页去哪了？
欢迎页已由首页取代。在项目菜单选择「关闭工程」可以回到首页。
首页进入了部室场景，怎么换回来？
这是看板娘模式。点击右上角的「切到经典首页」即可。
能同时打开两个工程吗？
可以。按 ⌘ + ⇧ + N（Windows / Linux 为 Ctrl + Shift + N）新建窗口，每个窗口打开一个工程。同一个工程只能在一个窗口打开。详见多窗口与多工程。
为什么找不到剧本工具栏的「演出」按钮？
这个入口已经移除。已有的镜头动画可以双击 Block 或从检查器打开演出设计视图，新的演出请使用演出段。卡片、纯文本、Ren’Py 和 JSON 也收进了工具栏左侧的下拉菜单，见剧本编辑器。
试用结束后找不到买过的激活码
在付款界面底部点击「我购买的激活码」，记录跟随付款时登录的账号，还没兑换的可以直接用于激活。详见付款、激活码与授权。
界面卡死或闪退后怎样反馈？
先保存能保存的内容，重新打开 Studio。在「设置 → 存储」打开运行日志目录，把 renderer-diagnostics.log、studio.log 和 studio.previous.log 附在反馈里。详见Studio 设置。
蓝图开启后为什么不按左侧章节顺序播放
蓝图改用图里的入口、节点和连线选择下一章。检查蓝图路线，或切回基础调度；切回后蓝图配置会保留。
找不到旧教程中的主题或角色类型切换
当前公开主题为经典、V3 彩色 A、琥珀织纹、春日书简、放课后纪事、电影居中、握草·原、看板娘。差分立绘是新建角色时选择的独立资源类型，常规角色表情支持图片与序列帧；见角色管理。
加载条为什么忽然跳到 100%
显示的是已完成资源项比例，缓存命中或资源较少时可能快速完成。等待界面的延迟只控制何时显示，不保证最短停留；见加载策略。
修改扩展源码后为什么还是旧界面
检查是否显示待构建，完成构建与项目发行物同步，再运行对应剧情。同步 SDK 不等于构建完成；见扩展开发。
录制灰掉或 Steam 没有反应
录制需要完整桌面程序提供服务，且调试画面已准备好；Steam 只在启用集成的桌面导出游戏中连接。分别查看录制与Steam的排查步骤。 
