【three.js教程】安装指南：从零搭建你的第一个 3D Web 项目

three.js 教程安装指南：从零搭建你的第一个 3D Web 项目

原文出处：Three.js Manual -- Installation

本文基于 three.js 官方手册的 Installation 章节整理而成，用更通俗的语言带你走完从建项目到部署上线的全流程。

写在前面

想在网页里做 3D？three.js 几乎是绕不开的选择。但在写第一行渲染代码之前，你得先把项目跑起来------这也是不少新手卡住的地方：到底用 npm 还是直接引 CDN？要不要装构建工具？import map 又是什么东西？

这篇指南会把这些疑问一次性讲清楚。我们先搭一个最基础的项目骨架，然后分别走两条路线------NPM + 构建工具 和CDN 直引------看看各自怎么开发、怎么上线，最后再聊聊插件怎么用、下一步学什么。

一、先把项目骨架搭起来

不管你后面选哪条路线，项目结构都是一样的。three.js 项目最少需要两个文件：

一个 HTML 文件，负责定义网页本身
一个 JS 文件，负责跑你的 3D 代码

下面这套命名不是强制的，但官方手册全程都在用，跟着走方便对照。

`index.html`

html 复制代码

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>My first three.js app</title>
    <style>
      body { margin: 0; }
    </style>
  </head>
  <body>
    <script type="module" src="/main.js"></script>
  </body>
</html>

`main.js`

js 复制代码

import * as THREE from 'three';

// ...你的 three.js 代码

`public/` 目录

这个目录也有人叫"静态目录"。顾名思义，里面的文件会被原封不动地推到网站上，不经过任何处理。贴图、音频、3D 模型这类资源文件通常都丢这里。

骨架搭好了，接下来就是让它在本地跑起来。官方给了两条路：用 NPM + 构建工具，或者直接从 CDN 引入。我们一个个看。

二、方式一：NPM + 构建工具（官方推荐）

先说结论：这是官方对大多数人的推荐方式。

为什么？因为项目稍微一复杂，依赖就会变多。静态托管搞不定的事情------比如导入本地 JS 文件、管理 npm 包------构建工具都能帮你自动处理，也不用操心 import map。开箱即用，省心。

开发阶段

第 1 步：装 Node.js

去 nodejs.org 下载安装就行。后面不管是管理依赖还是跑构建工具，都得靠它。

第 2 步：装 three.js 和 Vite

在项目目录下打开终端，依次执行：

bash 复制代码

# 装 three.js
npm install --save three

# 装 Vite（开发依赖，不进最终产物）
npm install --save-dev vite

Vite 只在开发时用，不会出现在你最终上线的网页里。当然，如果你更习惯 Webpack、Rollup 之类的其他构建工具，也没问题------只要是支持 ES Modules 的现代构建工具都行。
装完多了 node_modules/ 和 package.json，这俩是干嘛的？

package.json ：记录你装了哪些依赖、各自是什么版本。团队协作时，别人只要跑一下 npm install 就能装上一模一样的依赖环境。建议把它提交到版本管理。
node_modules/ ：依赖的实际代码都存在这里。Vite 构建时看到 import 'three'，就会自动来这里找文件。这个目录只在开发时用，不要上传到托管平台，也不要提交到版本历史。
想用 TypeScript？

three.js 本身是纯 JS，但社区维护了一套 TypeScript 类型定义，在这里：three-types/three-ts-types。

第 3 步：启动开发服务器

终端里敲一行：

bash 复制代码

npx vite

npx 又是什么？

简单说，npx 是跟着 Node.js 一起装上的，用来运行命令行工具（比如 Vite），省得你手动去 node_modules/ 里翻可执行文件。如果你嫌每次敲 npx 烦，也可以把 Vite 的常用命令写进 package.json 的 scripts 字段，以后直接 npm run dev 就行。

第 4 步：打开浏览器

没问题的话，终端会打印出一个类似 http://localhost:5173 的地址，点开就能看到你的应用了。这时候页面是空白的------别慌，这是正常的，说明环境已经就绪，接下来就可以创建场景了。

生产构建

开发完了，要上线怎么办？一行命令搞定：

bash 复制代码

npx vite build

Vite 会把项目用到的所有资源编译、压缩、优化，统一输出到 dist/ 目录。把这个目录的内容丢到你的服务器上，完事。

三、方式二：从 CDN 引入（不需要构建工具）

如果你不想装一堆 npm 的东西，或者只是想快速做个原型试试水，CDN 方式也是个选择。不过它需要对前面的项目结构做一点调整------多了一个叫 import map 的东西。

开发阶段

第 1 步：加 import map

问题出在哪？我们在 main.js 里写了 import ... from 'three'，但浏览器并不认识 'three' 这个包名------它不知道该去哪儿找这个文件。所以得在 index.html 里加一段 import map，相当于给浏览器一张"包名 → 网址"的对照表。

把下面这段放在 <head> 标签里、样式后面：

html 复制代码

<script type="importmap">
{
  "imports": {
    "three": "https://cdn.jsdelivr.net/npm/three@<version>/build/three.module.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/three@<version>/examples/jsm/"
  }
}
</script>

别忘了 ：把 <version> 替换成实际的版本号，比如 "v0.149.0"。最新版本可以去 npm 版本列表查。

第 2 步：启动本地服务器

你可能想问：既然都从 CDN 加载了，为啥还要本地服务器？直接双击 HTML 打开不行吗？

技术上能打开，但很多后续要用到的功能（比如加载外部模型）在 file:// 协议下会因为安全策略而失效。所以还是老老实实起个本地服务器吧。

装好 Node.js 后，在项目目录下跑：

bash 复制代码

npx serve .

第 3 步：打开浏览器

终端会给出类似 http://localhost:3000 的地址，打开即可。和 NPM 方式一样，页面此时是空白的------环境就绪，可以创建场景了。

不想用 serve？还有这些选择

本地静态服务器有很多，原理都差不多，挑顺手的用就行。
更多本地服务器选项

命令行工具（可能需要先装对应语言环境）：

命令	语言环境
`npx http-server`	Node.js
`npx five-server`	Node.js
`python -m SimpleHTTPServer`	Python 2.x
`python -m http.server`	Python 3.x
`php -S localhost:8000`	PHP 5.4+

图形界面工具（带窗口和 UI）：

Servez

编辑器插件（写代码时随手起个服务器）：

Five Server（VS Code）
Live Server（VS Code）
Live Server（Atom）

生产部署

CDN 方式上线特别简单：源文件直接传到托管商，不用构建、不用编译。

但便利是有代价的。你得自己盯着 import map，确保应用用到的所有依赖（以及依赖的依赖）都正确声明在里面。一旦 CDN 挂了，你的网站也会跟着挂。

重要提醒：所有依赖必须来自同一个 three.js 版本、同一个 CDN。混用不同来源的文件，轻则重复打包浪费体积，重则直接把应用搞崩。

四、两种方式怎么选？

说了这么多，到底该选哪个？简单对比一下：

维度	NPM + 构建工具（推荐）	CDN 引入
上手门槛	要懂点 npm、Vite	只要会写 import map
依赖管理	全自动	手动维护依赖链
开发体验	Vite 自带热更新，改完即时刷新	没有热更新，手动刷新
上线方式	`npx vite build` 编译优化	源文件直接传
离线可用	依赖都在本地	依赖于 CDN
适合谁	正经项目、依赖多	快速原型、教学演示

五、插件（Addons）怎么用？

three.js 开箱即用的部分是 3D 引擎的核心------场景、相机、渲染器、几何体、材质这些。但还有一些很常用的东西，比如轨道控制器（OrbitControls）、模型加载器（GLTFLoader）、后处理特效，它们放在 examples/jsm 目录里，统称为 addons（插件）。

插件不需要单独安装 ，但需要单独导入。比如你想用 OrbitControls 和 GLTFLoader，就这么写：

js 复制代码

import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

const controls = new OrbitControls( camera, renderer.domElement );
const loader = new GLTFLoader();

每个插件的文档或示例里一般也会写明怎么导入。另外，three.js 生态里还有不少第三方库，那些就得单独安装了，详见 Libraries and Plugins。

六、装完了，然后呢？

环境搭好、页面能跑，接下来就是真正写 3D 代码的时候了------去 Creating a Scene 创建你的第一个场景吧。

如果你想知道后面该怎么学，官方手册本身就是一个很好的路线图，大致是这样的：

入门：Installation → Creating a Scene → Drawing Lines → Creating Text
基础：Fundamentals → Responsive Design → Prerequisites → Setup
核心概念：Primitives、Scenegraph、Materials、Textures、Lights、Cameras、Shadows、Fog
进阶：Animation System、Color Management、Post Processing、Matrix Transformations
优化与实战：Optimizing Lots of Objects、Loading 3D Models、Picking、Voxel Geometry 等
新特性：WebGPU Renderer、WebXR（VR）

最后再多说一句：如果你拿不定主意选哪条路，就从 NPM + Vite 开始吧。前期享受自动依赖管理和热更新的便利，后期过渡到生产构建也顺理成章。CDN 方式留着做快速验证就好，但记住那条铁律------所有依赖，同版本、同来源。

【three.js教程】安装指南：从零搭建你的第一个 3D Web 项目