疑难解答

先看编辑器底部的问题面板：错误会阻止导出，警告不会阻止，但通常说明某条路径会在不该结束的地方结束。点击问题可跳到对应文件与行；修完后再用预览的“快进”和“上一步”走查主要分支。

项目打不开

看到的提示	常见原因	怎么修
不是 Kiny 项目（缺少 .kiw）	选中的不是项目根，或清单被移走了。	选择直接包含 project.kiw、唯一其它 .kiw 或兼容的 kiny.json 的文件夹；清单形状见项目结构。
项目根有多个 .kiw 文件	同一项目根留了两份新格式清单。	只保留当前作品对应的一份 .kiw；不要靠改扩展名保存备份。
<文件>.kiw 不是合法 JSON	清单少逗号、多逗号、引号不配对。	项目此时打不开；先用外部文本编辑器按项目结构的 JSON 形状修正。项目能重新打开后，才可继续用“项目设置”调整清单。
缺少或非法字段: entry	name、version、engine、entry 中某项缺失、为空或不是字符串。	补成非空字符串；entry 写入口文件的项目根相对路径。
entry 指向的文件不存在	清单里的入口路径拼错、文件被改名或不在项目里。	让 entry 与真实 .kin 相对路径完全一致，留意大小写。

预览空白或故事很快结束

最常见的不是播放器坏了，而是控制流已经结束：

• 开场只有 ~ let ...，却没写 -> 第一个节点。开场触底会直接结束，见项目结构：开场。
• 节点或子节点末尾出现“触底无显式出口”。补 -> 下一节点 或 -> END；节点之间不会自动落进下一段。
• 进入父节点后以为会自动进入第一个子节点。子节点没有默认入口，父节点正文必须显式 -> 子节点。
• 条件把全部普通选项都隐藏了。需要自动兜底时，在同组选项末尾放唯一一条 * -> 目标，见后备选项。
• 一行看起来像 [按钮文字] -> 目标，却漏了开头的 * 或 +。它会被当成正文加跳转；按提示补选项标记。

跳转、节点与名字报错

提示片段	原因与修正
节点不存在 / 跳转目标不存在	目标名拼错，或跨父节点跳子节点时漏了 父.子 完整路径。对照大纲；详见节点与跳转。
节点声明必须左右各 3 个等号	节点只能写 === 名字 ===；子节点才是左侧单个 =。
节点名不能包含空格	节点名可中文，但内部不能有空白；改成连写或下划线。
实参 … 个，节点需 … 个	带参节点的跳转参数数量不符。让 -> 节点(...) 与声明参数一一对应。
不能从外部跳进带参节点…的子节点	从节点外跳进子节点时无法建立父节点参数。先跳带参父节点，在其内部再跳子节点。
动态跳转表达式为空 / 动态跳转 … 之后不允许再接内容	-> {表达式} 的花括号里必须有值，右括号后不能追加调用参数。带参动态跳转用 $nodes.节点(实参) 先绑定。

变量、条件与分支报错

提示片段	原因与修正
引用未声明的变量	名字拼错，或变量只在另一个节点的局部作用域。需要跨节点的状态放到入口文件开场里声明。
全局变量/函数重复声明	不同 .kin 文件共享一个全局 JS 作用域。全项目搜索该名字，只留一个声明。
必须是 ASCII 标识符	变量、节点参数和选项标签不能用中文、空格或数字开头；正文和节点名仍可中文。
内置函数名不可作…	random、turns、seq 等是保留名；换一个作者变量名。
JS 片段语法错误	~ 行、~~~ 块或 {表达式} 里的 JavaScript 不完整。先核对括号、引号和运算符。
@else 前没有同层的 @if	@elif / @else 必须紧跟同层条件链；核对它与 body 行前面的 > 数量。
> 层级跳跃	一次多写了一层 >，但上一层没有选项或 @if 开启者。逐层对齐分支，见选项与分支。
一组选项内只能有一个 fallback	同组选项写了多条无文字的 * -> 目标。只保留一个。

命令、富文本与素材有问题

• 未知命令：@...：命令名拼错。尤其注意背景和音乐是 @bg_show、@bgm_play，不是缩写；查命令与函数索引。
• 命令应为 @名字(...) 形式 或 命令实参缺少右括号 )：命令必须顶格、独占一行，并带成对圆括号。不要在命令或跳转后追加行尾 // 注释；把注释放到独立一行。
• @input 第一个参数必须是变量名：第一项写已声明的裸变量，如 @input(player_name)，不要写字符串或 player.name。
• @panel 槽位错误：只接受字面量 "left"、"right"、"bottom"、"after"；模板用字符串。
• 未闭合的标签 / 孤立的闭标签：让 <b>、<color=...> 等成对并正确嵌套。未知标签会当普通文字，拼错不一定有你想要的样式。
• 非法颜色值、非法字号倍数、非法字体名、非法类名：颜色用十六进制或 CSS 具名色，字号用正数倍数；字体和类名不要放分号、括号等注入字符。完整边界见正文写作。
• 图片、声音或字体在你的电脑能用，交给别人却失效：路径必须相对项目根，文件名大小写要完全一致；不要写本机绝对路径。网页要交付整个导出文件夹，.kip 则重新打包后再发送。见导出独立网页和打包与分发。

导出、阅读与存档误解

“导出独立网页”是灰的。 问题面板仍有 error；先逐条修完。warning 不会禁用导出，但最好也确认。若有未保存改动，导出前的保存确认不能取消。

只发了 index.html，图片和声音没了。 独立网页的交付单位是整个 <作品名>-web 文件夹；二进制资源仍在相对目录中。

重命名作品后看不到旧网页存档。 新导出应沿用清单里的稳定 id，不要手改。浏览器存档还受域名、浏览器和设备隔离；换站点域名或清理浏览器数据不会自动迁移。

作品更新后某个旧存档读不了。 读取会重放原来的选择与输入。路径仍兼容就能继续；节点或选项变化让历史无法完整重放时，存档仍列出但会拒绝加载。这不是只看 version 清空。

Reader 与 Shelf 的书和存档为什么不互通。 两端都把导入内容和存档保存在自己的本地存储里，每次导入还有独立作品桶；它们不是云同步服务。差异见读者怎么读。

仍然定位不到

把问题缩成最小项目：保留一份 .kiw、入口 .kin 和能复现的最短分支；先在编辑器预览里复现，再记录问题面板的完整提示、文件名和行号。不要把 API key、私人路径或未公开稿件贴进公开 issue；提交前先删掉无关素材。