three.js 教程安装指南从零搭建你的第一个 3D Web 项目原文出处Three.js Manual – Installation本文基于 three.js 官方手册的 Installation 章节整理而成用更通俗的语言带你走完从建项目到部署上线的全流程。写在前面想在网页里做 3Dthree.js 几乎是绕不开的选择。但在写第一行渲染代码之前你得先把项目跑起来——这也是不少新手卡住的地方到底用 npm 还是直接引 CDN要不要装构建工具import map 又是什么东西这篇指南会把这些疑问一次性讲清楚。我们先搭一个最基础的项目骨架然后分别走两条路线——NPM 构建工具和CDN 直引——看看各自怎么开发、怎么上线最后再聊聊插件怎么用、下一步学什么。一、先把项目骨架搭起来不管你后面选哪条路线项目结构都是一样的。three.js 项目最少需要两个文件一个 HTML 文件负责定义网页本身一个 JS 文件负责跑你的 3D 代码下面这套命名不是强制的但官方手册全程都在用跟着走方便对照。index.html!DOCTYPEhtmlhtmllangenheadmetacharsetutf-8titleMy first three.js app/titlestylebody{margin:0;}/style/headbodyscripttypemodulesrc/main.js/script/body/htmlmain.jsimport*asTHREEfromthree;// ...你的 three.js 代码public/目录这个目录也有人叫静态目录。顾名思义里面的文件会被原封不动地推到网站上不经过任何处理。贴图、音频、3D 模型这类资源文件通常都丢这里。骨架搭好了接下来就是让它在本地跑起来。官方给了两条路用 NPM 构建工具或者直接从 CDN 引入。我们一个个看。二、方式一NPM 构建工具官方推荐先说结论这是官方对大多数人的推荐方式。为什么因为项目稍微一复杂依赖就会变多。静态托管搞不定的事情——比如导入本地 JS 文件、管理 npm 包——构建工具都能帮你自动处理也不用操心 import map。开箱即用省心。开发阶段第 1 步装 Node.js去 nodejs.org 下载安装就行。后面不管是管理依赖还是跑构建工具都得靠它。第 2 步装 three.js 和 Vite在项目目录下打开终端依次执行# 装 three.jsnpminstall--savethree# 装 Vite开发依赖不进最终产物npminstall--save-dev viteVite 只在开发时用不会出现在你最终上线的网页里。当然如果你更习惯 Webpack、Rollup 之类的其他构建工具也没问题——只要是支持 ES Modules 的现代构建工具都行。装完多了 node_modules/ 和 package.json这俩是干嘛的package.json记录你装了哪些依赖、各自是什么版本。团队协作时别人只要跑一下npm install就能装上一模一样的依赖环境。建议把它提交到版本管理。node_modules/依赖的实际代码都存在这里。Vite 构建时看到import three就会自动来这里找文件。这个目录只在开发时用不要上传到托管平台也不要提交到版本历史。想用 TypeScriptthree.js 本身是纯 JS但社区维护了一套 TypeScript 类型定义在这里three-types/three-ts-types。第 3 步启动开发服务器终端里敲一行npx vitenpx 又是什么简单说npx是跟着 Node.js 一起装上的用来运行命令行工具比如 Vite省得你手动去node_modules/里翻可执行文件。如果你嫌每次敲npx烦也可以把 Vite 的常用命令 写进package.json的scripts字段以后直接npm run dev就行。第 4 步打开浏览器没问题的话终端会打印出一个类似http://localhost:5173的地址点开就能看到你的应用了。这时候页面是空白的——别慌这是正常的说明环境已经就绪接下来就可以创建场景了。生产构建开发完了要上线怎么办一行命令搞定npx vite buildVite 会把项目用到的所有资源编译、压缩、优化统一输出到dist/目录。把这个目录的内容丢到你的服务器上完事。三、方式二从 CDN 引入不需要构建工具如果你不想装一堆 npm 的东西或者只是想快速做个原型试试水CDN 方式也是个选择。不过它需要对前面的项目结构做一点调整——多了一个叫import map的东西。开发阶段第 1 步加 import map问题出在哪我们在main.js里写了import ... from three但浏览器并不认识three这个包名——它不知道该去哪儿找这个文件。所以得在index.html里加一段 import map相当于给浏览器一张包名 → 网址的对照表。把下面这段放在head标签里、样式后面scripttypeimportmap{imports:{three:https://cdn.jsdelivr.net/npm/threeversion/build/three.module.js,three/addons/:https://cdn.jsdelivr.net/npm/threeversion/examples/jsm/}}/script别忘了把version替换成实际的版本号比如v0.149.0。最新版本可以去 npm 版本列表 查。第 2 步启动本地服务器你可能想问既然都从 CDN 加载了为啥还要本地服务器直接双击 HTML 打开不行吗技术上能打开但很多后续要用到的功能比如加载外部模型在file://协议下会因为安全策略而失效。所以还是老老实实起个本地服务器吧。装好 Node.js 后在项目目录下跑npx serve.第 3 步打开浏览器终端会给出类似http://localhost:3000的地址打开即可。和 NPM 方式一样页面此时是空白的——环境就绪可以创建场景了。不想用 serve还有这些选择本地静态服务器有很多原理都差不多挑顺手的用就行。更多本地服务器选项命令行工具可能需要先装对应语言环境命令语言环境npx http-serverNode.jsnpx five-serverNode.jspython -m SimpleHTTPServerPython 2.xpython -m http.serverPython 3.xphp -S localhost:8000PHP 5.4图形界面工具带窗口和 UIServez编辑器插件写代码时随手起个服务器Five ServerVS CodeLive ServerVS CodeLive ServerAtom生产部署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就这么写import*asTHREEfromthree;import{OrbitControls}fromthree/addons/controls/OrbitControls.js;import{GLTFLoader}fromthree/addons/loaders/GLTFLoader.js;constcontrolsnewOrbitControls(camera,renderer.domElement);constloadernewGLTFLoader();每个插件的文档或示例里一般也会写明怎么导入。另外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、WebXRVR最后再多说一句如果你拿不定主意选哪条路就从 NPM Vite 开始吧。前期享受自动依赖管理和热更新的便利后期过渡到生产构建也顺理成章。CDN 方式留着做快速验证就好但记住那条铁律——所有依赖同版本、同来源。