Three.js 官网怎么切换不同版本文档

一、为什么 Three.js 官网上找不到版本切换按钮？

很多从 Vue、React 或 Python 等生态转到 Three.js 的开发者，习惯了在官方文档顶部或侧边栏点击下拉菜单切换版本（例如选择 v16 或 v18）。但在打开 Three.js 官方文档时，左侧侧边栏只有语言切换选项（en、zh 等）和搜索输入框，找不到任何历史版本号的切换入口。

出现这种现象的核心原因在于 Three.js 官方站点的定位与维护机制。Three.js 官网是一个托管在 GitHub Pages 上的轻量静态站点，官方团队的核心精力聚焦于主干分支（master）的高频演进，每个月发布一次新版本（例如 r168、r169、r170）。为了保持线上站点精炼，官方服务器并没有为每个历史小版本单独生成多目录并存的在线归档。

然而，Three.js 并非严格遵循主版本号不兼容的语义化版本控制（SemVer）。在由 r120 迈向 r160+ 的演进过程中，次版本号的更迭伴随着大量的核心接口重构：

• 几何体体系重构：早期的 Geometry 类已被彻底废弃并移除，全面由底层缓冲区驱动的 BufferGeometry 代替；
• 色彩空间规范演进：贴图与渲染器的色彩编码从早期的 sRGBEncoding 迁移为 SRGBColorSpace，材质的高光与曝光参数亦有大幅调整；
• 光照物理单位升级：从早期的非物理线性光照过渡到默认开启的 useLegacyLights = false，相同光照强度在不同版本中呈现完全不同的画面亮度；
• 模块规范变动：早期的 CommonJS / Examples 扩展文件存放于 js/ 目录，后续全部重构为纯 ES Module 并迁移至 jsm/ 目录。

如果在维护老项目时直接参照官网最新文档编写代码，极其容易引发 TypeError: THREE.xxx is not a constructor 或渲染黑屏等严重故障。

二、途径一：启动本地 node_modules 中的专属文档（最推荐）

如果你的项目已经通过 npm 或 yarn 安装了 Three.js，其实无需联网，你的项目内部就已经拥有了一份与代码版本 100% 精准契合的官方完整文档。

1. 查看当前工程安装的精确版本

在查阅文档之前，首先需要明确当前代码真正运行的 Three.js 版本。由于 package.json 中经常带有 ^ 或 ~ 范围符号，最准确的方法是检查实际安装的版本：

// 方式一：在浏览器控制台或项目入口文件中打印版本常量
import * as THREE from 'three';
console.log('当前运行版本:', THREE.REVISION);
// 输出示例：当前运行版本: 128

# 方式二：在项目终端中执行 npm 查询
npm list three --depth=0
# 示例输出：three@0.128.0

2. 定位文档目录与启动本地服务

在项目的根目录下，Three.js 的完整文档源码存放在：

./node_modules/three/docs/

特别注意：请勿直接在操作系统文件管理器中双击打开 index.html！

Three.js 文档页面采用了“外层导航框架 + 内容子 iframe”的架构，并通过 fetch 或 XMLHttpRequest 动态获取 list.json 目录索引文件。如果在浏览器中以本地文件协议（file:///...）直接打开，现代浏览器的同源安全策略（CORS / Origin Policy）会直接阻断跨帧通信与本地数据请求，导致侧边栏一片空白、搜索无响应或页面点击无法跳转。

3. 本地服务启动命令示例

解决本地安全沙箱限制的方法非常简单——使用任意轻量级 HTTP 静态服务器将其托管在 http://localhost 域下：

# 在项目根目录执行
npx serve node_modules/three/docs -p 8080

# 执行后在浏览器中打开 http://localhost:8080 即可完整使用带搜索、带中文切换的离线文档

cd node_modules/three/docs
python3 -m http.server 8080

# 访问 http://localhost:8080/

三、途径二：从 GitHub 官方仓库获取指定 Release Tag 文档

如果你还没有创建前端工程、电脑未安装 node_modules，或者需要跨版本横向对比（例如准备把老项目从 r132 升级到 r155，需要同时参考两份文档），直接从 GitHub 官方仓库获取历史 Tag 是最纯净的做法。

1. 网页直接下载源码包

1. 用浏览器访问 GitHub 上的 Three.js 仓库标签页：https://github.com/mrdoob/three.js/tags；
2. 在列表中找到你需要的版本标签（例如 r128、r136、r145 等）；
3. 点击对应版本的 Source code (zip) 下载压缩包并解压；
4. 解压后进入内部的 docs/ 文件夹，同样使用前文介绍的静态服务器命令启动即可。

2. 命令行浅克隆单版本标签（推荐开发者使用）

Three.js 仓库历史庞大，若直接 git clone 整个仓库会下载数个 G 的 Git 提交树与多媒体资源。推荐使用 --depth 1 参数只克隆指定标签的最新快照，仅需数秒即可完成：

# 仅浅克隆 r128 标签下的文件
git clone --depth 1 --branch r128 https://github.com/mrdoob/three.js.git three-r128-docs

# 进入 docs 目录并启动服务
cd three-r128-docs/docs
python3 -m http.server 8080

四、途径三：免下载在线静态镜像快速查阅

如果你正处于移动端查阅、临时借用他人电脑，或者只想快速确认某个参数在老版本中是否存在，不想下载任何文件，可以使用基于 GitHub 源码树搭建的静态加速镜像。

由于 GitHub 原生 raw 链接不解析 HTML MIME 类型，可以直接利用开源服务 raw.githack.com。只要按规则拼接 URL，就可以直接在浏览器中打开特定版本的文档页面：

# 示例 1：查阅 r128 版本在线文档
https://raw.githack.com/mrdoob/three.js/r128/docs/index.html

# 示例 2：查阅 r136 版本在线文档
https://raw.githack.com/mrdoob/three.js/r136/docs/index.html

# 示例 3：查阅 r150 版本在线文档
https://raw.githack.com/mrdoob/three.js/r150/docs/index.html

适用场景与边界：这种方式非常快捷，进入后同样可以在左下角切换中文；但由于依赖第三方开源代理，如果所在网络环境访问 GitHub 静态资源较慢，可能会出现偶尔加载延迟的情况。日常主力开发依然推荐本地静态服务。

五、版本差异处理：善用官方 Migration Guide

许多开发者之所以需要“切换查看不同版本文档”，往往是因为在项目升级或引入第三方示例时遇到了报错。如果逐字逐页比对两版文档，不仅费时费力，而且很难发现深层逻辑变化。

针对跨版本改动，Three.js 维护者在官方 GitHub Wiki 中整理了完整的 Migration Guide（迁移指南）。该维基按版本发布顺序（例如 r127 -> r128、r128 -> r129）详细记录了每一个小版本中的变更细节：

• Deprecated（弃用声明）：哪些旧方法还能工作但已输出警告日志；
• Removed（删除移除）：哪些类或方法已被正式物理删除，对应的替代写法是什么；
• Behavioral Changes（表现与底层机制变更）：如默认材质贴图色彩管理、光源衰减物理公式的调整等。

六、快速决策与最佳实践总结

在实际开发与维护 Three.js 项目时，请根据当前所处的阶段选择最为高效的文档获取途径：