安装

项目结构

每个 three.js 项目至少需要一个 HTML 文件来定义网页，以及一个 JavaScript 文件来运行你的 three.js 代码。下面的结构和命名方式并非强制要求，但为了保持一致性，本指南将始终使用这种方式。

  • index.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 
    import * as THREE from 'three';

...
  • public/
    • public/ 文件夹有时也被称为"static"（静态）文件夹，因为其中的文件会原封不动地发布到网站上。通常纹理、音频和 3D 模型会放在这里。

现在我们已经搭建好了基本的项目结构，接下来需要一种方式在本地运行项目并通过浏览器访问它。安装和本地开发可以通过 npm 和构建工具来完成，也可以通过从 CDN 导入 three.js 来实现。下面将分别介绍这两种方式。

方式一：使用 NPM 和构建工具安装

开发

从 [link:https://www.npmjs.com/ npm 包注册表] 安装并使用 [link:https://eloquentjavascript.net/10_modules.html#h_zWTXAU93DC 构建工具] 对大多数用户来说是推荐的方式——你的项目依赖越多，就越可能遇到静态托管难以解决的问题。使用构建工具时，导入本地 JavaScript 文件和 npm 包无需 import map 即可直接使用。

  1. 安装 [link:https://nodejs.org/ Node.js]。我们需要它来管理依赖和运行构建工具。

  2. 在项目文件夹中打开 [link:https://www.joshwcomeau.com/javascript/terminal-for-js-devs/ 终端]，安装 three.js 和构建工具 [link:https://vitejs.dev/ Vite]。Vite 仅在开发过程中使用，不会成为最终网页的一部分。如果你更喜欢使用其他构建工具也没问题——我们支持任何能导入 [link:https://eloquentjavascript.net/10_modules.html#h_zWTXAU93DC ES Modules] 的现代构建工具。 

    # three.js
npm install --save three

# vite
npm install --save-dev vite
  3. 在终端中运行： 
    npx vite
  4. 如果一切顺利，你会在终端中看到一个类似 http://localhost:5173 的 URL，打开该 URL 即可查看你的 Web 应用。

页面将是空白的——你已经准备好创建一个场景了。

如果你想在继续之前了解更多关于这些工具的信息，请参阅：

  • [link:https://threejs-journey.com/lessons/local-server three.js journey: 本地服务器]
  • [link:https://cn.vite.dev/guide/cli Vite: 命令行接口]
  • [link:https://developer.mozilla.org/zh-CN/docs/Learn_web_development/Extensions/Client-side_tools/Package_management MDN: 包管理基础]

生产环境

稍后，当你准备部署 Web 应用时，只需让 Vite 执行生产构建——npx vite build。应用使用的所有内容都会被编译、优化并复制到 dist/ 文件夹中。该文件夹的内容即可直接托管到你的网站上。

方式二：从 CDN 导入

开发

不使用构建工具进行安装需要对上述项目结构做一些修改。

  1. 我们在 main.js 中从 'three'（一个 npm 包）导入了代码，但浏览器并不知道这意味着什么。在 index.html 中，我们需要添加一个 [link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap import map] 来定义从哪里获取该包。将以下代码放在 <head></head> 标签内，样式之后。 

    <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> 替换为 three.js 的实际版本号，例如 "v0.149.0"。最新版本可以在 [link:https://www.npmjs.com/package/three?activeTab=versions npm 版本列表] 中找到。

  2. 我们还需要运行一个本地服务器来将这些文件托管到浏览器可以访问的 URL 上。虽然技术上可以双击 HTML 文件在浏览器中打开，但出于安全原因，我们后续要实现的重要功能在以这种方式打开页面时无法正常工作。

    安装 [link:https://nodejs.org/ Node.js]，然后在项目目录中运行 [link:https://www.npmjs.com/package/serve serve] 来启动本地服务器： 

    npx serve .
  3. 如果一切顺利，你会在终端中看到一个类似 http://localhost:3000 的 URL，打开该 URL 即可查看你的 Web 应用。

页面将是空白的——你已经准备好 [link:#manual/introduction/Creating-a-scene 创建一个场景] 了。

还有许多其他本地静态服务器可供选择——有些使用 Node.js 以外的语言，有些是桌面应用程序。它们的工作方式基本相同，下面列出了一些替代方案。

更多本地服务器

命令行

命令行本地服务器从终端窗口运行。可能需要先安装相应的编程语言。

  • 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+)

图形界面

图形界面本地服务器以应用程序窗口的形式在你的计算机上运行，可能带有用户界面。

  • [link:https://greggman.github.io/servez Servez]

代码编辑器插件

一些代码编辑器提供插件，可按需启动简单服务器。

  • [link:https://marketplace.visualstudio.com/items?itemName=yandeu.five-server Five Server]，适用于 Visual Studio Code
  • [link:https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer Live Server]，适用于 Visual Studio Code
  • [link:https://atom.io/packages/atom-live-server Live Server]，适用于 Atom

生产环境

当你准备部署 Web 应用时，只需将源文件推送到你的网站托管服务商——无需构建或编译任何内容。这种方式的缺点是，你需要小心地确保 import map 与应用所需的所有依赖（以及依赖的依赖！）同步更新。如果托管这些依赖的 CDN 暂时宕机，你的网站也会停止工作。

重要提示：所有依赖都应从同一版本的 three.js 和同一个 CDN 导入。混合使用不同来源的文件可能导致代码被重复引入，甚至以意想不到的方式破坏应用。

附加组件

three.js 开箱即用地包含了 3D 引擎的基础功能。其他 three.js 组件——如控制器、加载器和后期处理效果——属于 [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm addons/] 目录的一部分。附加组件不需要单独安装，但需要单独导入。

下面的示例展示了如何导入 three.js 以及 `OrbitControls` 和 `GLTFLoader` 附加组件。在必要时，每个附加组件的文档或示例中也会提到这一点。 

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。这些需要单独安装——请参阅库和插件。

下一步

你现在已经准备好创建一个场景了。