安装([name])

项目结构

每个 three.js 项目至少需要一个 HTML 文件来定义网页,以及一个 JavaScript 文件来运行你的 three.js 代码。下面的结构和命名选择并非必需,但为了保持一致性,本指南将在全文中使用。

  • index.html
    1. <!DOCTYPE html>
    2. <html lang="en">
    3. <head>
    4. <meta charset="utf-8">
    5. <title>My first three.js app</title>
    6. <style>
    7. body { margin: 0; }
    8. </style>
    9. </head>
    10. <body>
    11. <script type="module" src="/main.js"></script>
    12. </body>
    13. </html>
  • main.js

    1. import * as THREE from 'three';
    2. ...
  • public/
    • public/ 文件夹有时也被称为 “静态(static)”文件夹,因为其中包含的文件会原封不动地推送到网站上。纹理(textures)、音频和 3D 模型通常会放在这里。

现在我们已经建立了基本的项目结构,便需要一种方法在本地运行并通过浏览器访问它。我们可以使用 npm 和构建工具来完成安装和本地开发,也可以从 CDN 导入 three.js。下面将对这两种方案进行说明。

方案 1:使用 NPM 和构建工具进行安装

开发

对于大多数用户而言,从 npm 包注册表中心 安装并使用 构建工具 会是一个更推荐的方案。因为项目需要的依赖越多,就越有可能遇到静态托管无法轻易解决的问题。而使用构建工具,导入本地 JavaScript 文件和 npm 软件包将会是开箱即用的,无需导入映射(import maps)。

  1. 安装 Node.js。我们需要它来管理依赖项和运行构建工具。
  2. 在项目文件夹中通过 终端 安装 three.js 和构建工具 Vite。Vite 将在开发过程中使用,但不会被打包成为最终网页的一部分。当然,除了 Vite 你也可以使用其他支持导入 ES Modules 的现代构建工具。
  1. # three.js
  2. npm install --save three
  3. # vite
  4. npm install --save-dev vite

  1. 在终端运行:
    1. npx vite
  2. 如果一切顺利,你会在终端中看到一个类似 http://localhost:5173 的 URL,打开该 URL 就能看到你的网络应用程序。

目前页面将会是空白的,不过你已经准备好可以开始创建一个场景了。

如果你想在继续之前进一步了解这些工具,请参阅:

生产

之后,当你准备部署网络应用程序时,只需要让 Vite 运行生产构建 - npx vite build。应用程序使用的所有内容都将被编译、优化并复制到 dist/ 文件夹中。该文件夹中的内容就可以托管到你的网站上了。

方案 2:从 CDN 导入

开发

在不使用构建工具的情况下进行安装,需要对上述项目结构进行一些修改。

  1. 我们在 main.js 中从 “three”(一个 npm 软件包)导入了代码,但网络浏览器并不知道这意味着什么。在 index.html 中,我们需要添加一个导入映射(import map)来定义从哪里获取软件包。将下面的代码放在 <head></head> 标签内、样式(styles)之后。

    1. <script type="importmap">
    2. {
    3. "imports": {
    4. "three": "https://cdn.jsdelivr.net/npm/three@<version>/build/three.module.js",
    5. "three/addons/": "https://cdn.jsdelivr.net/npm/three@<version>/examples/jsm/"
    6. }
    7. }
    8. </script>

    不要忘记将上述链接中的 <version> 替换为 three.js 的实际版本,如 "v0.149.0"。最新版本可在 npm 版本列表中找到。

  2. 我们还需要运行一个 本地服务器,将这些文件托管到网络浏览器可以访问的 URL 上。虽然从技术上讲,双击 HTML 文件并在浏览器中打开它是可行的,但出于安全原因,这样打开的页面无法使用我们稍后要使用的重要功能。

    安装 Node.js,然后运行 serve 在项目目录中启动本地服务器:

    1. npx serve .
  3. 如果一切顺利,你会在终端中看到一个类似 http://localhost:3000 的 URL,打开该 URL 就能看到你的网络应用程序。

目前页面将会是空白的,不过你已经准备好可以开始创建一个场景了。

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

更多本地服务器 ### 命令行(Command Line) 命令行本地服务器通过终端窗口运行。可能需要先安装相关的编程语言。 - 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+) ### GUI GUI 本地服务器在计算机上以应用程序窗口的形式运行,并可以有一个用户界面。 - Servez ### 代码编辑器的插件 有些代码编辑器的插件可以按需生成一个简单的服务器。 - Visual Studio Code:Five Server - Visual Studio Code:Live Server - Atom:Live Server

生产

当你准备部署

网络应用时,只需将源文件推送给网络托管服务提供商即可,无需构建或编译任何内容。这样做的坏处是,你需要注意根据应用程序所需的依赖项(以及依赖项的依赖项!)不断更新导入映射。如果托管你的依赖项的 CDN 暂时宕机,你的网站也会停止工作。

重要提示: 请将所有依赖项从同一版本的 three.js 导入,并从相同的 CDN 上获取。混合使用不同来源的文件可能导致包含重复代码,甚至以意想不到的方式破坏应用程序。

附加组件(Addons)

开箱即用的 three.js 包含 3D 引擎的基本要素。而其他 three.js 组件,如控件(controls)、加载器(loaders)和后期处理效果(post-processing effects)则属于 addons/ 目录的一部分。附加组件无需单独 安装,但需要单独 导入

下面的示例展示了如何导入 three.js 的 OrbitControlsGLTFLoader 附加组件。必要时每个附加组件的文档或示例中也会提及这一点。

  1. import * as THREE from 'three';
  2. import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
  3. import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
  4. const controls = new OrbitControls(camera, renderer.domElement);
  5. const loader = new GLTFLoader();

一些优秀的第三方项目也可用于 three.js。这些项目需要单独安装,请参见 库和插件

下一步

是时候开始创建一个场景了。