怎么处理引擎版本差异How to handle engine version differences

这篇解决什么：跨版本产生的三类漂移 —— AI 给的代码面向旧版本、你查的文档不是你的版本、导出模板和项目版本不匹配。它们大多不是「AI 能力」问题，而是版本事实没有被固定下来。

What this guide solves: three kinds of version drift — code from AI that targets an old version, documentation that is not for your version, and export templates that do not match the project. Most of it is not an "AI capability" problem; it is a version fact nobody pinned down.

适用条件

• ✅ 你在用 AI 生成引擎代码，且项目有（或愿意现在定出）一个明确版本
• ✅ 你考虑升级引擎，或正被「这段代码在我这跑不通」困扰
• ⚠ 不适用：还没选引擎 —— 版本支持本来就是选择条件之一，见 S1 · 选引擎
• 各引擎的版本策略（大版本节奏、LTS 与否）请以官方文档为准；本站不跑引擎，也不比较哪个引擎版本更省心（没有依据）。

When this applies

• ✅ You generate engine code with AI and your project has (or will now get) one explicit version
• ✅ You are considering an upgrade, or you keep hitting "this code does not run here"
• ⚠ Not before the engine is chosen — version support is a selection condition: S1 · Pick an engine
• Each engine's version policy (major cycles, LTS or not) is decided by its official docs. This site runs no engines and compares none — there is no basis here for claiming any engine "manages versions better".

步骤

1. 写下版本基线。 一行进项目记录：引擎版本号、脚本语言版本、导出模板版本、文档版本入口（URL）。没有这行，后面全是口头争论。

2. 只读对应版本的文档。 多数引擎的官方文档按版本分开 —— 我们 2026-11-06 实际看到：Godot 4.3 的文档索引页独立存在且自标 outdated；Unity 在线手册的 URL 里直接带版本号 6000.6；PixiJS 文档挂 8.x 路径。核对你的版本入口，别读「最新版」时以为是你的版。

3. AI 给的代码先对文档再运行。 判断顺序：这个 API 在你的版本文档里存在吗 → 用法与文档一致吗 → 才轮到运行验证（运行验收走 怎么验收 AI 生成的游戏代码）。

4. 旧代码报错先比对，不点改。 跨大版本的重命名与结构调整，官方迁移文档通常有清单 —— 例如 PixiJS 官方有 v7→v8 迁移指南，three.js 官方仓库的 Migration Guide 页按版本记录破坏性改动（链接见文末核验表）。逐处猜测改法，最容易改出半新半旧的混合体。

5. 试验版与项目版分开装。 学新版本用一个独立安装，项目版本不动 —— 与 S1 · 选引擎 里「按目标版本核对」是同一条纪律。

6. 升级走固定顺序。 读官方迁移清单 → 备份项目 → 先只升引擎、不改代码跑一次 → 按清单逐项改 → 重跑验收与导出（Web 构建注意导出模板必须与项目版本配套：Godot 官方 Web 导出文档写明需要可用的导出模板，见核验表）。

The steps

1. Write the version baseline. One line in the project record: engine version, scripting language version, export-template version, and the URL of your docs entry. Without it everything after is hearsay.

2. Read only your version's docs. Official docs are usually split per version — seen by us on 2026-11-06: the Godot 4.3 docs index exists on its own and marks itself outdated; a Unity online-manual URL carries the version 6000.6 in its path; PixiJS docs live under an 8.x path. Find your version's entry point instead of assuming the "latest" page describes you.

3. Check AI's code against your docs before running it. Order: does this API exist in your version's docs → is the usage as documented → only then run (running is covered by How to accept AI-generated game code).

4. When old code fails, diff against the migration list — do not patch by guesswork. Official guides usually list the renames and structural changes: PixiJS has an official v7→v8 migration guide, and the three.js repository's official Migration Guide wiki records breaking changes per release (links in the table at the end). Guessing change-by-change produces half-migrated code.

5. Install experiment versions separately from project versions. Learn a new version in its own install; the project's version stays put — the same discipline as "check against the target version" in S1 · Pick an engine.

6. Upgrade in a fixed order. Read the official migration list → back up → upgrade the engine only and run once → apply changes item by item → re-run acceptance and export. For web builds the export template must match the project version: Godot's web-export docs state a runnable export template is required (see the table).

一个可走查的例子

⚠ 本例的版本、现象与报错文本是虚构示例，只为演示流程；本站没有运行过任何引擎。

• 输入：项目基线记录为 4.3（虚构）。AI 交回一段协程写法被 3.x 使用、4.x 已变的脚本（虚构情况 —— 具体哪个语法在哪版怎么变，以对应版本文档为准，本站不代写结论）。
• 处理：第 3 步核对：在该版本文档中查找这个写法 → 未找到同名 API；打开 4.3 文档索引页（页面自标 outdated，指向 stable）确认当前写法的文档入口。
• 结果判断：失败 —— 代码面向的版本与项目基线不一致，属于版本问题而不是逻辑 bug；不要在此状态下「改到能跑」。
• 失败后下一步：把目标版本号与该页文档 URL 一起给 AI，要求按此版本重写并引用该页；重写后回到验收流程重走。

A walk-through example

⚠ The versions, symptoms and error text here are a fictitious example to show the flow; this site has run no engine.

• Input: the baseline line says 4.3 (invented). AI returns a script whose coroutine style was 3.x usage that 4.x changed (situation invented — which syntax changed in which version is decided by that version's docs; this site does not write those conclusions for you).
• Processing: step-3 check: look for that construct in your version's docs → no API of that name found; open the 4.3 docs index (it marks itself outdated and points to stable) to locate the current wording's entry.
• Result: fail — the code targets a different version than the baseline. That is a version problem, not a logic bug; do not "tweak until it runs" in this state.
• After the failure: give AI the target version number together with that docs page's URL, require a rewrite to that version citing the page; then re-enter the acceptance flow.

失败分支

Failure branches

下一步

• 引擎档案里记录了各引擎的版本相关事实与出处：引擎档案
• 定完基线后的代码检查流程：怎么验收 AI 生成的游戏代码

Next steps

• Engine profiles carry version-relevant facts with their sources: Engine profiles
• The code check after pinning the baseline: How to accept AI-generated game code