怎么下载Three.js本地文件用于离线开发

在无网络或内网封闭环境中进行 Three.js 开发，核心在于下载两部分本地静态文件：核心渲染引擎 three.module.js 与项目所需的扩展模块（例如轨道控制器 OrbitControls.js）。随后在本地页面中使用现代浏览器原生支持的 <script type="importmap"> 将模块名映射至本地相对路径，并通过系统自带工具启动极简的本地 HTTP 静态服务。只要完成这几个环节，无需连接任何外部网络即可在浏览器中顺畅进行 3D 页面开发与交互调试。

一、为什么不能只下载一个 three.min.js？核心文件组成梳理

在很多传统 Web 开发经验中，离线使用一个库通常只需要去官网或 CDN “右键另存为”一个单独的压缩文件（例如 jquery.min.js），然后在 HTML 中用 <script src="./jquery.min.js"></script> 引入即可。

这种做法在早期版本的 Three.js 中确实可以勉强运转，因为早期的 three.min.js 会将所有 API 绑定到全局对象 window.THREE 上。然而在现代前端标准下，这种单文件模式在稍具实用性的 3D 项目中会迅速遇到瓶颈：

• 现代 Three.js 全面转向 ES 模块化（ES Module）：现代官方文档、示例以及各类插件均以 import * as THREE from 'three' 的语法组织代码。如果依然依赖全局注入的旧版单文件，将无法直接运行官方示例提供的各类组件。
• 常用功能不在核心库内，而在拓展包（JSM）中：像我们最常用的鼠标视角旋转（OrbitControls）、3D 模型加载器（GLTFLoader、OBJLoader）、后期特效合成器（EffectComposer）等，官方均未打包在核心库内，而是独立存放在 examples/jsm/ 目录下。
• 扩展模块自带内部依赖：查看任何一个官方 JSM 插件（如 OrbitControls.js），它的第一行几乎都是 import { ... } from 'three';。这意味着即使你把控制器下载到本地，它依然依赖一个名为 'three' 的核心模块。在没有外部网络协助解析时，浏览器原生无法识别这个名称，除非进行本地路径映射。

因此，搭建离线环境时，我们要获取并保存的是一个“核心库 + 扩展插件目录”的组合，而不是孤立的一个 .js 文件。

二、获取 Three.js 本地文件的三种常用方式

获取这些文件有几种直接而稳定的途径，根据你的开发习惯和现有网络条件进行选择即可：

方式一：从 GitHub Releases 下载完整源码归档包（推荐）

这是最彻底、资产最齐全的离线化方式。Three.js 在 GitHub 上公开发布每一个版本的完整 Zip 压缩包。

1. 使用有网络的电脑访问 GitHub 上的 Three.js 仓库 Releases 页面（https://github.com/mrdoob/three.js/releases）。
2. 在对应版本（例如 r160、r170 等）下方，找到 Source code (zip) 并下载到本地。
3. 解压该压缩包。解压后的文件夹体积较大（包含大量测试和文档），此时我们只需要提取其中两个核心目录：
   • build/three.module.js：这是核心库，复制到你的工程 libs/ 目录下。
   • examples/jsm/：这是全部官方扩展插件库，将其中的 controls/、loaders/ 等子文件夹或整个 jsm/ 目录复制到你的工程 libs/jsm/ 目录下。
4. 提取完成后，其余无关测试代码和文档均可删除，本地静态资源包即准备就绪。

方式二：通过 CDN 镜像地址精准下载单文件（轻量按需）

如果你只需要制作一个极小的演示项目，不想下载数百兆的完整归档源码包，可以直接通过公共 CDN 镜像针对性下载几个文件：

• 核心库地址（以 jsDelivr 为例）：
  https://cdn.jsdelivr.net/npm/three@0.160.0/build/three.module.js
  在浏览器打开该链接，按快捷键 Ctrl + S（Mac 上为 Cmd + S）另存为 three.module.js。
• 视角控制器地址：
  https://cdn.jsdelivr.net/npm/three@0.160.0/examples/jsm/controls/OrbitControls.js
  同样另存为 OrbitControls.js，并保存在本地项目的 libs/jsm/controls/ 目录下。

方式三：借助 npm 缓存提取静态文件

如果开发机虽然不能直连外网，但在内网有 npm 镜像源，或者你可以在有网电脑上执行 npm：

npm install three

安装完成后，直接进入 node_modules/three/ 目录：

• 从 node_modules/three/build/three.module.js 复制出核心库；
• 从 node_modules/three/examples/jsm/ 复制出所有扩展文件。

三、离线项目目录规划与 Import Map 本地映射配置

下载好文件后，如何组织本地工程目录是离线开发能否顺利运行的关键。推荐建立如下清晰的目录结构：

my-offline-threejs/
├── index.html                    # 本地页面入口
└── libs/                         # 本地第三方库目录
    ├── three.module.js           # 核心构建库
    └── jsm/                      # 扩展功能目录
        └── controls/
            └── OrbitControls.js  # 常用轨道控制器

为什么必须在 HTML 中配置 Import Map？

当我们查看 OrbitControls.js 的源码时，会发现其导入语句为：

import { EventDispatcher, Vector3, ... } from 'three';

这里的 'three' 是一个裸模块说明符（Bare Specifier）。在脱离打包工具（如 Webpack、Vite）且脱离外部网络 CDN 的原生浏览器环境中，浏览器无法知道 'three' 对应磁盘上的哪一个文件。如果不做处理，控制台将直接抛出严重错误：

TypeError: Failed to resolve module specifier "three". Relative references must start with either "/", "./", or "../".

解决这个问题的标准做法是在 index.html 中引入 <script type="importmap">，在本地将裸模块名重定向到本地相对文件路径：

<script type="importmap">
{
  "imports": {
    "three": "./libs/three.module.js",
    "three/addons/": "./libs/jsm/"
  }
}
</script>

配置好这一段映射后，本地离线代码就可以书写成与官方线上范例完全一致的语法风格：

<script type="module">
  import * as THREE from 'three';
  import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

  // 此时浏览器会自动将 'three' 解析为 './libs/three.module.js'
  // 将 'three/addons/controls/OrbitControls.js' 解析为 './libs/jsm/controls/OrbitControls.js'
</script>

四、运行协议辨析：为什么断网环境下仍必须启动本地 HTTP 服务？

很多刚接触离线 Web 3D 开发的同学最容易产生的困惑是：“既然所有文件都下载到了本地，为什么我直接双击 index.html 网页却是一片空白？”

双击 HTML 文件时，浏览器使用的是 file:/// 协议。在此协议下，现代浏览器的安全策略（CORS 和同源隔离策略）会将页面 Origin 认定为 null。此时：

• 所有通过 <script type="module"> 发起的外部 ES 模块文件加载都会被浏览器安全层无条件拦截；
• 后续如果需要离线加载 3D 模型文件（.gltf、.glb）或纹理贴图图片（.png、.jpg），fetch 请求同样会被 file:/// 协议直接扼杀。

因此，“离线运行”并不等同于“直接双击文件”。所谓的离线，是指我们的计算机不需要接入外部公网，但本机内部仍然需要一个微型的本地 HTTP 静态服务器（运行在 http://localhost 或 http://127.0.0.1 本地回环接口上）。这不会消耗任何流量，也不需要互联网信号。

常用极简本地服务器启动方式：

1. Python 3 内置模块（绝大多数电脑自带，推荐）：

打开终端进入你的工程根目录 my-offline-threejs/，输入以下命令并回车：

python3 -m http.server 8000

执行后终端会输出服务启动状态（以下为示例输出）：

2. Node.js 环境：

npx serve .

3. VS Code 编辑器插件：

在编辑器中安装 Live Server 插件，右键 index.html 选择 Open with Live Server 即可。

五、完整可运行的本地离线验证用例

下面是一个完整的、包含场景创建、光照渲染、立方体自转以及 OrbitControls 鼠标交互的 index.html 文件代码。你可以将它直接保存到项目根目录中进行验证。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Three.js 本地离线开发运行验证</title>
  <style>
    body {
      margin: 0;
      overflow: hidden;
      background-color: #1a1a1a;
      font-family: sans-serif;
    }
    #info {
      position: absolute;
      top: 15px;
      left: 15px;
      color: #ffffff;
      background: rgba(0, 0, 0, 0.6);
      padding: 10px 16px;
      border-radius: 6px;
      font-size: 13px;
      pointer-events: none;
    }
  </style>

  <!-- 1. 本地 Import Map 映射，必须置于任何业务 module 脚本之前 -->
  <script type="importmap">
  {
    "imports": {
      "three": "./libs/three.module.js",
      "three/addons/": "./libs/jsm/"
    }
  }
  </script>
</head>
<body>
  <div id="info">Three.js 本地离线运行成功！支持鼠标拖拽旋转、滚轮缩放。</div>

  <!-- 2. 业务渲染逻辑脚本 -->
  <script type="module">
    import * as THREE from 'three';
    import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

    // 创建场景
    const scene = new THREE.Scene();

    // 创建透视相机
    const camera = new THREE.PerspectiveCamera(
      60,
      window.innerWidth / window.innerHeight,
      0.1,
      1000
    );
    camera.position.set(3, 3, 5);

    // 创建 WebGL 渲染器
    const renderer = new THREE.WebGLRenderer({ antialias: true });
    renderer.setSize(window.innerWidth, window.innerHeight);
    renderer.setPixelRatio(window.devicePixelRatio);
    document.body.appendChild(renderer.domElement);

    // 接入本地轨道控制器
    const controls = new OrbitControls(camera, renderer.domElement);
    controls.enableDamping = true; // 启用阻尼平滑

    // 添加环境光与平行光
    const ambientLight = new THREE.AmbientLight(0xffffff, 0.6);
    scene.add(ambientLight);

    const dirLight = new THREE.DirectionalLight(0xffffff, 0.8);
    dirLight.position.set(5, 10, 7);
    scene.add(dirLight);

    // 添加辅助网格地面
    const gridHelper = new THREE.GridHelper(10, 10, 0x8A9478, 0x444444);
    scene.add(gridHelper);

    // 创建一个带有光泽的标准几何体
    const geometry = new THREE.BoxGeometry(1.5, 1.5, 1.5);
    const material = new THREE.MeshStandardMaterial({
      color: 0x8A9478,
      roughness: 0.3,
      metalness: 0.2
    });
    const cube = new THREE.Mesh(geometry, material);
    cube.position.y = 0.75;
    scene.add(cube);

    // 窗口尺寸自适应
    window.addEventListener('resize', () => {
      camera.aspect = window.innerWidth / window.innerHeight;
      camera.updateProjectionMatrix();
      renderer.setSize(window.innerWidth, window.innerHeight);
    });

    // 动画循环
    function animate() {
      requestAnimationFrame(animate);

      // 立方体慢速自转
      cube.rotation.y += 0.008;

      // 更新控制器阻尼
      controls.update();

      // 执行渲染
      renderer.render(scene, camera);
    }

    animate();
  </script>
</body>
</html>

实机断网验证步骤：

1. 将电脑的 Wi-Fi 关闭，或拔出网线，确保处于彻底无网络连接的离线环境。
2. 在工程根目录下打开终端，运行 python3 -m http.server 8000。
3. 打开任意现代浏览器（Chrome、Edge、Safari、Firefox），地址栏输入 http://localhost:8000。
4. 如果页面中央出现带网格地面的橄榄绿渐变立方体，按住鼠标左键可以任意视角旋转、滚轮可以缩放，并且按 F12 打开控制台没有任何报错，即证明本地离线开发环境已完全搭建成功。

六、常见报错排查与总结清单

在离线开发过程中，如果遇到白屏或加载失败，请对照以下三类最常见的错误进行排查：

综上所述，下载 Three.js 本地文件并用于离线开发并不复杂。关键在于理清“核心库 + 扩展插件”的完整文件构成，利用现代浏览器原生的 Import Map 化解离线模块路径解析难题，并始终通过本地回环 HTTP 静态服务来规避跨域限制。遵循这套规范，不论是出差旅途、封闭内网还是现场演播，都能稳定、自给自足地开展 3D 前端项目的构建与调试。