Three.js怎么安装：npm引入与CDN加载方法

一、npm 引入方式：面向工程化项目的完整安装流程

在真实的前端业务开发中，Three.js 通常不是单独存在的一个脚本，而是与业务逻辑、状态管理以及构建工具深度结合的第三方模块。通过 npm 安装，能够将 Three.js 纳入统一的依赖清单 package.json 中进行版本管理，并充分利用打包工具的代码摇树（Tree-shaking）、按需加载以及 TypeScript 类型推断能力。

1. 环境准备与工程初始化

在执行安装前，需确保本地已经安装了 Node.js（建议版本 Node 18 或更高）及 npm。打开系统终端，创建一个专用的工程文件夹并进入该目录，随后生成基础的依赖配置文件：

# 创建并进入工程文件夹
mkdir three-starter
cd three-starter

# 初始化 package.json 清单
npm init -y

初始化完成后，当前目录会生成一个默认的 package.json 文件。如果后续直接使用原生 ES 模块语法而无需特殊 Babel 转译，建议在 package.json 中添加 "type": "module" 字段。

2. 安装 Three.js 核心包与类型声明

在终端中执行以下命令安装 Three.js 核心包：

npm install three

该命令会从 npm 官方仓库下载 Three.js 源码至 node_modules/three，并将依赖声明写入 dependencies。如果你使用 TypeScript 进行开发，或者希望在 VS Code 等编辑器中获得完整的参数提示与类型注解，还可以安装社区维护的类型声明包：

npm install -D @types/three

3. 在代码中引入核心库与扩展组件

现代版本的 Three.js 严格遵循 ES 模块规范。在项目脚本（例如 main.js）中，通过标准解构或整体导入即可引入核心命名空间：

// 导入 Three.js 核心命名空间
import * as THREE from 'three';

// 导入官方扩展插件（如轨道控制器、模型加载器）
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

4. 启动开发服务器与渲染验证

为了验证 Three.js 是否成功安装并正常工作，建议搭配轻量级前端构建工具 Vite。执行以下命令安装 Vite 并编写验证页面：

# 安装轻量构建工具 Vite
npm install -D vite

在项目根目录下新建 index.html，内容如下：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8" />
  <title>Three.js npm 引入验证</title>
  <style>
    body { margin: 0; overflow: hidden; }
    canvas { display: block; }
  </style>
</head>
<body>
  <script type="module" src="./main.js"></script>
</body>
</html>

在同级目录新建 main.js，编写包含场景、透视相机、几何体与渲染循环的最小验证代码：

import * as THREE from 'three';

// 1. 创建场景与透视相机
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
camera.position.z = 4;

// 2. 创建几何体与材质，生成网格模型
const geometry = new THREE.BoxGeometry(1.5, 1.5, 1.5);
const material = new THREE.MeshBasicMaterial({ color: 0x52677D, wireframe: true });
const cube = new THREE.Mesh(geometry, material);
scene.add(cube);

// 3. 创建渲染器并挂载至页面
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

// 4. 动画循环
function animate() {
  requestAnimationFrame(animate);
  cube.rotation.x += 0.01;
  cube.rotation.y += 0.01;
  renderer.render(scene, camera);
}
animate();

最后在终端中执行启动指令：

npx vite

终端会输出本地访问地址（如 http://localhost:5173/）。在浏览器中打开该地址，如果屏幕中央出现一个持续旋转的蓝灰色线框立方体，且浏览器控制台（Console）无报错，即说明 npm 引入配置成功。

二、CDN 加载方式：无需构建工具的快速引入方案

如果只是为了临时验证某段着色器代码、复现三维数学公式，或者编写简单的技术演示，搭建一套完整的前端工程可能会显得过于繁重。此时，直接使用 CDN 资源是最快的方式。

1. 为什么不能直接使用普通的全局 script 标签？

很多初学者在查看较老的文档时，会尝试用 <script src=".../three.min.js"> 加载。然而，从 r150 版本之后，Three.js 官方已正式移除了传统的 UMD 全局变量构建版本，全面转向 ES 模块（ESM）。在原生 ESM 下，如果直接写 import * as THREE from 'three'，浏览器在没有额外配置的情况下会由于无法识别裸模块名称 'three' 而抛出致命解析错误。

2. 现代解法：使用 Import Maps（导入映射）

现代主流浏览器（Chrome 89+、Edge 89+、Firefox 108+、Safari 16.4+）原生支持了 <script type="importmap"> 规范。它允许我们在 HTML 头部定义一个 JSON 映射表，告诉浏览器当代码请求 "three" 或 "three/addons/" 时，应当从哪个具体的远程 CDN URL 拉取脚本。

3. 单文件完整示例（可直接运行）

新建一个名为 cdn-demo.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 CDN 加载与 Import Maps 示例</title>
  <style>
    body { margin: 0; overflow: hidden; background-color: #F8FAFC; }
    canvas { display: block; }
  </style>

  <!-- 1. 定义导入映射表：必须在任何模块脚本运行之前声明 -->
  <script type="importmap">
    {
      "imports": {
        "three": "https://unpkg.com/three@0.160.0/build/three.module.js",
        "three/addons/": "https://unpkg.com/three@0.160.0/examples/jsm/"
      }
    }
  </script>
</head>
<body>
  <!-- 2. 声明 type="module"，在脚本中使用标准 import 语法 -->
  <script type="module">
    import * as THREE from 'three';
    import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

    // 创建场景
    const scene = new THREE.Scene();
    scene.background = new THREE.Color(0xF8FAFC);

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

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

    // 添加鼠标轨道控制器
    const controls = new OrbitControls(camera, renderer.domElement);
    controls.enableDamping = true;

    // 添加环境光与平行光
    const ambientLight = new THREE.AmbientLight(0xffffff, 0.8);
    scene.add(ambientLight);
    const dirLight = new THREE.DirectionalLight(0xffffff, 1.2);
    dirLight.position.set(5, 10, 7);
    scene.add(dirLight);

    // 创建一个受光照影响的网格几何体
    const geometry = new THREE.TorusKnotGeometry(1, 0.35, 100, 16);
    const material = new THREE.MeshStandardMaterial({ 
      color: 0xA66C5B, 
      roughness: 0.3, 
      metalness: 0.2 
    });
    const knot = new THREE.Mesh(geometry, material);
    scene.add(knot);

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

    // 渲染循环
    function animate() {
      requestAnimationFrame(animate);
      knot.rotation.y += 0.01;
      controls.update();
      renderer.render(scene, camera);
    }
    animate();
  </script>
</body>
</html>

三、关键注意事项与常见报错排查

在实际安装和引入过程中，开发者最容易遇到以下三个典型错误：

1. 报错：Failed to resolve module specifier "three"

表现：控制台抛出红色错误 Uncaught TypeError: Failed to resolve module specifier "three". Relative references must start with either "/", "./", or "../".
原因：在没有经过 Vite / Webpack 等打包工具编译的普通 HTML 中直接书写了 import * as THREE from 'three'，且未在页面上方配置 <script type="importmap">。浏览器无法根据裸模块名猜测 CDN 实际网络地址。
解决办法：如果是工程化项目，确认使用了开发服务器运行；如果是纯 HTML 页面，检查是否在模块脚本前正确补全了包含 "three": "..." 的 importmap 声明。

2. 报错：Cannot read properties of undefined 或材质/组件行为异常

表现：引入 OrbitControls 或模型加载器后，控制台提示对象未定义，或 3D 场景完全黑屏。
原因：版本不匹配。例如核心包引入的是 three@0.160.0，而在 three/addons/ 中引入了最新版或未指定版本的 three@latest。Three.js 迭代非常频繁，不同小版本之间内部类结构可能变动。
解决办法：在 importmap 或 package.json 中，务必将核心库与扩展组件的版本号完全锁死为一致的具体版本（如全套统一为 0.160.0）。

3. 报错：Access to script at '...' from origin 'null' has been blocked by CORS policy

表现：页面空白，控制台明确指出 CORS 限制或模块加载被拦截。
原因：直接双击了本地 HTML 文件，Origin 为 null。
解决办法：在项目目录运行命令行 npx serve 或使用任何本地静态 Web 服务器，通过 http://localhost:... 进行调试访问。

四、两种引入方式的选型对比与总结

npm 依赖引入与 CDN 脚本加载并非互斥关系，而是各自定位于不同的使用阶段和应用场景。下表与架构总结图梳理了两者的核心差异：

简而言之，如果是准备开发正式的 Web3D 应用，建议从一开始就使用 npm install three 配合 Vite 搭建工程体系，这样能够省去后续迁移构建的成本；而如果仅仅是想在一个小时内验证某个数学模型或特效着色器，使用 CDN 结合 Import Maps 编写单文件 HTML 则能够让你以最快的速度看到三维渲染效果。