Three.js入门指南：从零搭建本地开发环境与文档系统-优快云博客

1. 为什么你需要一个本地的Three.js开发环境？

如果你刚开始接触Three.js，可能会觉得有点懵。看着官网那些酷炫的3D例子，自己也想动手试试，但第一步就卡住了：代码该往哪写？怎么跑起来？更头疼的是，Three.js的官方文档（docs）和示例库（examples）都在GitHub上，每次想查个API或者看个效果，都得打开浏览器，等半天加载，网速不好的时候简直急死人。这种体验，就像你想学做菜，但菜谱和食材都放在一个遥远的仓库，每次看菜谱都得跑一趟，太折腾了。

我刚开始学Three.js那会儿，就深受其苦。官网的加载速度时快时慢，调试代码时频繁切换窗口，思路很容易被打断。后来我发现，把整个Three.js的“工具箱”搬到本地，是最高效的做法。这不仅仅是把代码下载下来那么简单，而是搭建一个完整的、离线的学习和开发沙箱。在这个沙箱里，你可以：

秒开文档：API手册、类说明、属性方法，随查随有，不用再忍受网络延迟。
随时“偷师”：官方提供了海量的示例（examples目录），每个都是绝佳的学习素材。本地部署后，你可以直接运行、修改、打断点调试，理解每个效果背后的代码逻辑。
源码级调试：遇到诡异的问题，可以直接追溯到src目录下的源码，看看Three.js内部到底是怎么处理的，这对于深入理解原理至关重要。
稳定的开发环境：不依赖外网，你的学习进度和项目开发不会因为网络波动而中断。

简单说，搭建本地环境，就是为你自己建立一个专属的、高速的、功能齐全的Three.js“图书馆”和“实验室”。接下来，我就手把手带你从零开始，把这个环境建起来，过程比你想的简单。

2. 第一步：获取Three.js的“全家桶”

万事开头难，但这一步真的不难。Three.js是一个完全开源的项目，它的所有“家当”都放在GitHub上。我们有两种主流方式把它请到你的电脑里。

2.1 方式一：直接下载“稳定版”压缩包（推荐新手）

这是最直接、最不容易出错的方法，特别适合刚开始接触Git和Node.js的朋友。

打开Three.js的GitHub仓库：在浏览器里访问 https://github.com/mrdoob/three.js。你会看到满屏的英文和代码，别慌，我们的目标很明确。
找到下载按钮：在页面中间偏上的位置，找到一个绿色的按钮，上面写着 “Code”。点击它，在弹出的菜单里选择 “Download ZIP”。这个ZIP文件包含了当前主分支（通常是稳定版本）的全部代码、文档和示例。
解压到合适的位置：下载完成后，把这个ZIP文件解压到你电脑上一个你容易找到的目录。比如，我习惯在D:\Dev或者~/Documents/Dev下面创建一个threejs文件夹，专门放这些东西。这里有个非常重要的提醒：你选择的整个路径里，最好不要包含任何中文字符！ 比如“D:\学习资料\threejs”这种路径，后续在命令行操作时可能会引发一些意想不到的编码错误，所以直接用英文或拼音目录最省心。

解压后，你会看到一个名为three.js-master的文件夹，里面就是宝藏了。我们来快速认识一下几个核心目录，这能帮你后续更好地利用它们：

build/：这里是编译好的Three.js库文件。你平时在HTML里通过<script src="...">引入的three.js或three.min.js就来自这里。对于学习，我们更关注源码，但部署项目时会用到它。
docs/：这就是我们梦寐以求的离线文档！ 里面是所有的API文档页面。直接打开index.html是没法正常看的，需要一个小型服务器来运行，后面我们会搞定它。
examples/：黄金学习素材库。包含了官方提供的上百个示例，从最简单的几何体到复杂的后期处理、物理引擎、VR/AR应用都有。每个示例都是一个独立的HTML文件，是学习的最佳参考。
src/：Three.js引擎的源代码。所有你调用的类、函数、数学库都在这。想成为高手，迟早要来这里逛逛。
editor/：一个基于浏览器的简易3D场景编辑器，有点像简化版的Blender，可以直接在网页里摆模型、调灯光、导场景。

2.2 方式二：使用Git克隆（适合有经验的开发者）

如果你熟悉Git，或者打算长期跟进Three.js的更新，那么克隆仓库是更好的选择。这能让你随时通过git pull拉取最新的提交和特性。

打开你的终端（Windows用PowerShell或CMD，Mac/Linux用Terminal），切换到你想要存放项目的目录，然后执行：

git clone https://github.com/mrdoob/three.js.git

这条命令会在当前目录下创建一个three.js文件夹，内容和下载ZIP包得到的基本一致。用这种方式，你得到的是一个完整的Git仓库，可以查看历史提交、切换分支等。

无论你选择哪种方式，现在你的电脑上已经有了Three.js的完整“源代码+文档+示例”三件套。接下来，我们要让它“活”起来。

3. 第二步：配置本地文档服务器（告别卡顿）

拿到了docs文件夹，但直接双击里面的index.html，浏览器很可能只会显示一片空白或者乱码。这是因为文档网站依赖本地服务器环境来正确处理模块化和资源加载。别担心，Three.js社区已经为我们准备好了开箱即用的工具。

3.1 安装Node.js环境

本地服务器需要Node.js来驱动。如果你还没安装，去Node.js官网（https://nodejs.org）下载最新的**LTS（长期支持版）**并安装。安装过程很简单，一路“下一步”即可。安装完成后，打开终端，输入以下命令来验证是否成功：

node -v
npm -v

如果这两条命令分别输出了Node.js和npm（Node的包管理器）的版本号，比如v18.xx.x和9.x.x，那么恭喜你，环境准备就绪。

3.2 一键启动文档服务

Three.js项目根目录下有一个package.json文件，它定义了项目的依赖和脚本。我们只需要安装这些依赖，然后运行一个命令。

用VSCode打开项目：强烈推荐使用Visual Studio Code作为你的开发工具。直接把刚才解压（或克隆）的three.js-master（或three.js）文件夹拖到VSCode窗口里打开。
打开集成终端：在VSCode里，按快捷键 Ctrl+` （反引号键，在Tab键上面）或者点击顶部菜单的“终端”->“新建终端”。这时，终端的工作目录应该就是你项目的根目录。
安装项目依赖：在终端里输入以下命令并回车：
```
npm install
```
这个命令会读取package.json，自动下载所有需要的工具和库（比如构建工具Rollup、小型服务器Servez等）。第一次运行可能会花上几分钟，取决于你的网速，请耐心等待。过程中会刷出很多日志，只要最后没有红色的ERROR报错，就是成功了。你会看到多了一个node_modules文件夹，里面就是下载的依赖包。
启动文档服务：依赖安装好后，在同一个终端里输入：
```
npm start
```
回车后，你会看到终端开始滚动输出信息。稍等片刻，当看到类似下面这样的输出时，就说明服务启动成功了：
```
[HTTP] Serving "." at http://192.168.1.100:8080
```
或者更简单的 Server running at http://localhost:8080。
访问本地文档：按住 Ctrl 键（在Mac上是 Cmd 键），同时用鼠标点击终端里输出的那个链接（通常是 http://localhost:8080）。你的默认浏览器就会打开一个页面。

现在，你看到的就是运行在你自己电脑上的Three.js文档网站！速度飞快，毫无延迟。页面左侧是导航栏，你可以点击 docs/ 进入API文档，点击 examples/ 浏览所有官方示例，点击 editor/ 使用在线编辑器。你可以把它加入浏览器书签，以后随时访问。

3.3 个性化配置（可选但实用）

默认的服务运行在8080端口。如果你电脑上的8080端口已经被其他程序（比如另一个本地项目）占用了，启动时会报错。别急，我们可以轻松修改端口。

打开项目根目录下的package.json文件，找到"scripts"部分。里面有一行看起来像这样：

"dev": "concurrently --names \"ROLLUP,HTTP\" -c \"bgBlue.bold,bgGreen.bold\" \"rollup -c utils/build/rollup.config.js -w -m inline\" \"servez -p 8080\"",

注意最后的 \"servez -p 8080\"。这里的8080就是端口号。你可以把它改成任何未被占用的端口，比如9000、3000等。修改后保存文件，然后先按Ctrl+C停止当前服务，再重新运行npm start，服务就会在新的端口上启动了。

4. 第三步：将文档变成“常驻服务”（更省心）

用npm start启动服务固然方便，但有个小问题：每次你想查文档，都得先打开VSCode，在终端里敲命令。有没有办法让它像百度一样，随时打开浏览器就能访问呢？有！我们可以利用操作系统自带的Web服务器功能，让它一直运行在后台。

这里以Windows系统为例，介绍如何使用IIS（Internet信息服务）来托管我们的Three.js文档目录。Mac用户可以使用Apache或Nginx，原理类似。

4.1 启用Windows的IIS功能

IIS是Windows自带的Web服务器，但默认不安装。我们需要先把它打开。

在Windows搜索框输入“启用或关闭Windows功能”，并打开它。
在弹出的窗口列表中，找到 “Internet Information Services”，勾选它前面的复选框。点击“确定”，Windows会自动安装所需的组件。这个过程可能需要几分钟，并可能要求重启电脑。

4.2 在IIS中创建网站

安装完成后，我们配置一个专门的网站来指向我们的Three.js文档。

再次在搜索框输入“IIS管理器”并打开。
在左侧连接面板，展开你的电脑名，你会看到“网站”文件夹。右键点击“网站”，选择“添加网站...”。
在弹出的对话框中填写信息：
- 网站名称：起个容易识别的名字，比如 ThreejsLocalDocs。
- 物理路径：点击“...”按钮，选择你解压的Three.js文件夹的根目录（就是包含docs、examples的那个文件夹）。
- 绑定：IP地址保持“全部未分配”就好，这样既可以用localhost访问，也可以用本机IP访问。端口号填一个没被占用的，比如 9000。记住这个端口号。
- 其他设置保持默认，点击“确定”。

4.3 启用目录浏览功能

现在，如果你在浏览器访问 http://localhost:9000，可能会看到403错误或者一片空白。这是因为IIS默认会寻找像index.html、default.aspx这样的默认文档，而我们的Three.js根目录下没有这些文件，它只是一个包含子文件夹的目录。

我们需要告诉IIS：“如果找不到默认页面，就把目录列表显示出来”。

在IIS管理器左侧，点击你刚刚创建的网站 ThreejsLocalDocs。
在中间的功能视图面板里，找到“IIS”区域下的 “目录浏览” 图标，双击它。
在右侧的“操作”面板中，点击 “启用”。

4.4 享受成果

现在，重新在浏览器里访问 http://localhost:9000。奇迹发生了！你看到了一个清晰的目录列表，里面有docs/、examples/、editor/等文件夹。点击docs/，就能进入离线文档；点击examples/，就能浏览所有示例。由于IIS是Windows的一项系统服务，它会随系统启动而自动运行（除非你手动停止这个网站）。这意味着，只要你电脑开着，这个本地文档站就一直在那里，随时待命。你可以把这个链接 http://localhost:9000/docs 直接加入浏览器收藏夹，以后查API就是一次点击的事，和学习效率直接挂钩。

5. 第四步：探索与利用你的本地宝库

环境搭好了，服务跑起来了，现在我们来好好逛逛这个本地宝库，看看怎么用它来真正提升你的学习和开发效率。

5.1 高效查阅API文档

本地文档和官网内容完全同步，但速度快了不止一个量级。我常用的几个技巧：

左侧导航树：docs/页面左侧有完整的API结构树。从核心的Scene、Camera、Renderer，到几何体Geometry、材质Material、光源Light，再到加载器Loader、动画Animation等，一应俱全。多点点，熟悉整体结构。
页面内搜索：大多数浏览器都支持页面内查找（Ctrl+F）。在具体的API页面，比如BoxGeometry的页面，你可以快速查找“parameters”、“methods”等关键词，定位到你关心的部分。
中英文切换：Three.js官方文档是多语言的。在文档页面的右上角，通常有一个语言选择下拉框，你可以切换到中文（如果可用）。但我的建议是，尽量适应英文文档，因为更新最及时，社区讨论也大都基于英文术语。

5.2 从官方示例（examples）中“偷师”

examples/目录是我认为Three.js项目中最有价值的部分之一。这里有超过200个独立的HTML示例文件，覆盖了几乎所有特性。

按图索骥：当你想实现某个效果（比如阴影、粒子系统、模型加载）但不知从何下手时，直接去examples/目录下找。你可以通过文件名的关键词来搜索，或者直接一个个点开看预览图。
源码即教程：打开一个示例的HTML文件，比如webgl_animation_cloth.html。不要只看运行效果，一定要查看网页源代码（在浏览器中右键 -> 查看页面源代码）。你会看到完整的、可运行的HTML、CSS和JavaScript代码。这是最直接、最权威的学习材料。你可以把代码复制到你的本地项目中，一点点修改参数，观察变化，理解每一行代码的作用。
调试与修改：因为示例就在你的本地，你可以用浏览器的开发者工具（F12打开）随意地打断点、查看变量、修改CSS样式，而不用担心影响任何线上服务。这种“为所欲为”的调试体验，是线上示例无法提供的。

5.3 结合源码（src）进行深度理解

当你使用某个API遇到奇怪的行为，或者想知道某个函数内部的实现逻辑时，src/目录就是你的终极答案之书。

快速定位：比如你在文档里看到THREE.Mesh这个类，想知道它的raycast方法如何实现。你可以在VSCode中，对整个src目录进行全局搜索（Ctrl+Shift+F），搜索关键词“Mesh”，很快就能找到src/objects/Mesh.js这个文件。打开它，就能看到raycast方法的完整实现。
理解设计模式：阅读Three.js的源码，你能学到很多优秀的JavaScript编程模式和3D图形学概念的组织方式。比如它是如何管理内存的（dispose方法）、如何构建场景图的、如何设计材质系统的。这对于你从“会用”进阶到“精通”至关重要。

6. 第五步：开启你的第一个本地Three.js项目

有了强大的本地文档和示例库作为后盾，现在可以信心满满地开始写你自己的第一个Three.js程序了。我们不依赖任何线上CDN，完全在本地环境中进行。

创建项目文件夹：在你的工作区（不要放在Three.js源码目录里），新建一个文件夹，例如my-first-three。
引入Three.js库：你有两个选择：
- 直接引用构建好的文件：从Three.js源码目录的build/文件夹里，复制three.min.js（压缩版，体积小）到你的项目文件夹里。然后在HTML中用<script src="three.min.js"></script>引入。
- 使用ES6模块（现代推荐）：这是更现代的方式。在你的项目文件夹里，通过npm init -y初始化一个项目，然后通过npm install three来安装Three.js库。这样你就可以在JavaScript文件中使用import * as THREE from 'three';来引入了。这种方式可以利用打包工具（如Vite、Webpack）的优势。对于第一个极简示例，我们选择第一种直接引用的方式，最直观。

编写HTML文件：在你的项目文件夹里创建一个index.html文件，写入以下代码：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>My First Three.js</title>
    <style>
        body { margin: 0; }
        canvas { display: block; }
    </style>
</head>
<body>
    <!-- 引入本地的Three.js库 -->
    <script src="./three.min.js"></script>
    <script>
        // 1. 创建场景
        const scene = new THREE.Scene();

        // 2. 创建相机（透视相机）
        const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
        camera.position.z = 5;

        // 3. 创建渲染器
        const renderer = new THREE.WebGLRenderer();
        renderer.setSize(window.innerWidth, window.innerHeight);
        document.body.appendChild(renderer.domElement);

        // 4. 创建一个立方体
        const geometry = new THREE.BoxGeometry();
        const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 });
        const cube = new THREE.Mesh(geometry, material);
        scene.add(cube);

        // 5. 动画循环
        function animate() {
            requestAnimationFrame(animate);
            cube.rotation.x += 0.01;
            cube.rotation.y += 0.01;
            renderer.render(scene, camera);
        }
        animate();
    </script>
</body>
</html>

运行与调试：直接用浏览器打开这个index.html文件（双击即可）。你应该能看到一个旋转的绿色立方体。恭喜你，你的第一个完全基于本地环境的Three.js程序运行成功了！
遇到问题？查！：如果代码运行没效果，打开浏览器的开发者工具（F12）查看控制台（Console）是否有红色报错。根据错误信息，回到你的本地文档网站（http://localhost:9000/docs），搜索相关的类名（如WebGLRenderer、BoxGeometry），仔细核对API的用法。也可以去examples/目录下找一个显示立方体的例子，对比一下代码差异。

这就是一个完整的本地开发闭环：编码 -> 运行 -> 遇到问题 -> 秒查本地文档/参考本地示例 -> 解决问题 -> 继续编码。整个过程流畅无阻，你的注意力可以完全集中在学习和创造上，而不是等待网页加载或者寻找资料上。

我花了很长时间才意识到，搭建一个顺手的本地环境，其价值不亚于学会Three.js本身的几个核心API。它从根本上改变了你和这个强大工具互动的方式，从被动的“查阅者”变成了主动的“探索者”。当你把文档、示例、源码都放在触手可及的地方时，学习曲线会变得平缓，解决问题的速度会快得多。希望这份指南能帮你扫清入门的第一道障碍，接下来，就尽情地在3D的世界里构建你的奇思妙想吧。记住，本地环境就是你的大本营，从这里出发，去探索examples里的星辰大海，遇到任何疑惑，docs和src里总有答案。