Three.js开发环境搭建教程：浏览器、VS Code、本地服务器与Node.js配置指南

本节目标：把写 three.js 需要的环境配好：浏览器、编辑器、本地服务器、Node.js。学完你能新建项目，并用浏览器跑起来第一个页面。

需要准备什么

写 three.js 不需要多好的电脑。一张能跑浏览器的集成显卡就够，用慢电脑甚至更好——你能提前体验到大多数用户的真实性能。

需要四样东西：

现代浏览器：Chrome、Edge、Firefox、Safari 都行
文本编辑器：推荐 VS Code
本地服务器：后面讲为什么必需
Node.js（可选）：用 npm 装包时才需要

检查浏览器是否支持 WebGL2

r163 起 three.js 只支持 WebGL2。好消息是：2026 年的现代浏览器全部支持 WebGL2。不放心的可以做个检测，把下面代码保存为 html 文件，双击用浏览器打开：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8" />
  <title>WebGL2 检测</title>
</head>
<body>
  <script>
    const canvas = document.createElement('canvas');
    const gl = canvas.getContext('webgl2');
    if (gl) {
      document.body.innerHTML = '✅ 支持 WebGL2，可以运行 three.js r185';
    } else {
      document.body.innerHTML = '❌ 不支持 WebGL2，请升级浏览器';
    }
  </script>
</body>
</html>

也可以去 caniuse.com 搜索 WebGL2，查看各浏览器的支持情况。

浏览器选哪个？开发阶段推荐 Chrome 或 Edge：开发者工具最顺手，调试 three.js 的体验最好。Firefox 和 Safari 平时用没问题，但有些调试功能弱一些。手机端浏览器基本都支持 WebGL2，调试时可以手机访问电脑的局域网地址，验证移动端效果。真机测试的方法：手机和电脑连同一个 Wi-Fi。电脑启动 Live Server 后，终端会输出局域网地址（一般是 http://192.168.x.x:5500），手机浏览器直接访问。第一次连不上，多半是电脑防火墙拦了端口，放行即可。电脑的局域网 IP 可以在终端用 ipconfig（Windows）或 ifconfig（Mac）查到。

安装 VS Code

VS Code 是目前最主流的网页开发编辑器，免费开源。装好后建议再装两个扩展：

Live Server：一键启动本地服务器，作者 Ritwick Dey
Prettier：保存时自动格式化代码

装完后建一个项目文件夹，比如 threejs-tutorial，用 VS Code 打开这个文件夹，在里面新建 index.html。VS Code 会自动识别 HTML 并高亮语法。以后打开项目都从「文件夹」打开，不要单个文件打开，这样终端路径、文件跳转都正常。写代码时终端也经常要用：VS Code 里按 Ctrl+` 打开集成终端，不用另外开窗口。终端就是命令行窗口，往里输入命令、回车执行，Node 和 Python 的命令都在终端里跑。

为什么需要本地服务器

双击打开 HTML 用的是 file:// 协议。简单页面没问题，但两种情况会失败：

ES Module（import/export 语法）在 file:// 下被浏览器安全策略拦截
加载纹理、模型等本地资源会被 CORS 拦截

具体报错长这样：Access to script at ‘file:///…’ from origin ‘null’ has been blocked by CORS policy。浏览器这么做是为了安全：file:// 下的页面没有”来源”概念，无法判断资源是否可信。

第 3 章起我们的代码就要用 import 语法，所以本地服务器是必需品，不是可选优化。

本地服务器做的事很简单：把文件夹里的文件通过 HTTP 协议提供给浏览器。浏览器访问 http://127.0.0.1:5500 时，服务器返回 index.html 和它引用的所有资源，一切看起来和线上网站一样。

Note

以后从教程复制的代码如果打开是空白页，先检查是不是直接用 file:// 双击打开的。

三种启动本地服务器的方式

任选一种，推荐第一种：

VS Code Live Server：装好扩展后，在 index.html 上右键 → Open with Live Server，浏览器自动打开 http://127.0.0.1:5500
Python：装了 Python 的话，在项目目录打开终端运行：

python -m http.server 8080

然后浏览器访问 http://localhost:8080

Node.js：装了 Node 的话，可以用 npx 临时启动：

npx serve

Tip

服务器启动后别关终端。改完代码刷新浏览器就能看到效果，不用重启服务器。

这里说的都是开发服务器，只服务你一个人调试。将来网站上线，用的是生产服务器（Apache、Nginx 或云厂商托管），那是部署阶段的事，现在不用管。

安装 Node.js（可选但推荐）

Node.js 是让 JavaScript 脱离浏览器运行的环境，npm 是它的包管理器。以后用 npm 安装 three.js、跑构建工具都要用到它。

去 nodejs.org 下载 LTS 版本，一路下一步安装。装完在终端验证：

node -v
npm -v

能看到版本号（比如 v22.x 和 10.x）就成功了。

装不装 Node 都不影响开始学 three.js：本教程的示例统一用 CDN（内容分发网络）在网页里直接加载 three.js，不需要 Node。CDN 怎么选、版本怎么锁，第 3 章详讲。

Note

如果你的电脑已经装过 Node，版本太旧（低于 18）的话建议升级到 LTS，避免某些新工具不兼容。

认识开发者控制台

所有浏览器都有开发者工具，按 F12 打开。控制台（Console）是最常用的调试工具：

看报错信息，红色显示
用 console.log 打印变量
临时执行 JavaScript 语句
过滤日志：输入 error 只看报错，输入 warn 只看警告

写 three.js 的前几周，你大概率天天和它打交道。遇到页面白屏，第一步永远是打开控制台看报错，而不是瞎改代码。另外两个常用面板：Elements 看 DOM 结构（确认 canvas 有没有被加进页面），Network 看资源加载（确认 three.js 文件有没有加载成功）。

项目目录结构

建议按下面的结构组织项目，现在只需要前两个文件：

threejs-tutorial/
├── index.html      # 页面入口
└── main.js         # three.js 代码

后面章节的示例基本都是这个结构：一个 HTML，一个或多个 JS 文件。保持简单，别一上来就上复杂框架。

环境检查清单

动手写代码前，花两分钟过一遍：

浏览器能打开 WebGL2 检测页面，显示 ✅
VS Code 装好了 Live Server
终端能执行 node -v 和 npm -v（装了 Node 的话）
用 Live Server 打开过任意一个 html 页面
按 F12 打开过开发者控制台，知道报错在哪里看

全过一遍，后面几章就不会卡在环境问题上。

常见坑

端口被占用：8080 起不来就换一个，比如 8081
Live Server 没生效：确认装的是「Live Server」扩展，别装错同名扩展
中文乱码：HTML 里记得写 <meta charset="UTF-8" />
手机访问不了电脑的服务器：确认手机和电脑在同一局域网，且防火墙放行了端口
改完代码页面没变化：先确认保存了文件，再确认刷新的是本地服务器地址，不是旧页面
服务器开了但页面打不开：确认访问的端口号和启动时输出的一致

环境配好了，下一节把 three.js 引入页面。