# 安装（[name]）

## 项目结构

每个 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）"文件夹，因为其中包含的文件会原封不动地推送到网站上。纹理（textures）、音频和 3D 模型通常会放在这里。

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

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

### 开发

对于大多数用户而已，从 [link:https://www.npmjs.com/ npm 包注册表中心] 安装并使用 [link:https://eloquentjavascript.net/10_modules.html#h_zWTXAU93DC 构建工具] 会是一个更推荐的方案。因为项目需要的依赖越多，就越有可能遇到静态托管无法轻易解决的问题。而使用构建工具，导入本地 JavaScript 文件和 npm 软件包将会是开箱即用的，无需导入映射（import maps）。

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 将在开发过程中使用，但不会被打包成为最终网页的一部分。当然，除了 Vite 你也可以使用其他支持导入 [link:https://eloquentjavascript.net/10_modules.html#h_zWTXAU93DC ES Modules] 的现代构建工具。

   `# three.js npm install --save three # vite npm install --save-dev vite`
   安装时我的项目中新增了 node_modules/ 和 package.json。它们是什么？

   npm 使用 package.json 来描述你已经安装的每个依赖项的版本。如果有其他人和你一起开发项目，他们只需运行 npm install 就能安装每个依赖项的原始版本。如果你在使用版本控制器（如：Git、SVN）来控制代码版本，那么 package.json 应当被提交。

   npm 将每个依赖项的代码放在 node_modules/ 下的文件夹中。当Vite构建应用程序时，它会看到 “three” 的导入，并自动从该文件夹中提取 three.js 文件。 node_modules/ 文件夹仅在开发过程中使用，不应上传到你的网络托管提供商或提交到版本历史记录中。

3. 在终端运行： `npx vite`
   npx 是什么？

   npx 与 Node.js 一同安装，可运行 Vite 等命令行程序，这样你就不必自己在 node_modules/ 中搜索正确的文件。如果你愿意，可以将 [link:https://vitejs.dev/guide/#command-line-interface Vite 的常用命令] 放入 [link:https://docs.npmjs.com/cli/v9/using-npm/scripts package.json:scripts] 列表，然后使用 npm run dev 代替。

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

目前页面将会是空白的，不过你已经准备好可以开始[link:#manual/zh/introduction/Creating-a-scene 创建一个场景]了。

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

- [link:https://threejs-journey.com/lessons/local-server three.js journey: Local Server]
- [link:https://vitejs.dev/guide/cli.html Vite: Command Line Interface]
- [link:https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Package_management MDN: Package management basics]

### 生产

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

## 方案 2：从 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> 标签内、样式（styles）之后。

   `<script type="importmap"> { "imports": { "three": "https://unpkg.com/three@<version>/build/three.module.js", "three/addons/": "https://unpkg.com/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 就能看到你的网络应用程序。

目前页面将会是空白的，不过你已经准备好可以开始[link:#manual/zh/introduction/Creating-a-scene 创建一个场景]了。

还有许多其他本地静态服务器可供选择——有些使用不同的语言而不是 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 本地服务器在计算机上以应用程序窗口的形式运行，并可以有一个用户界面。

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

### 代码编辑器的插件

有些代码编辑器的插件可以按需生成一个简单的服务器。

- Visual Studio Code：[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]
- Atom：[link:https://atom.io/packages/atom-live-server Live Server]

### 生产

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

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

## 附加组件（Addons）

开箱即用的 three.js 包含 3D 引擎的基本要素。而其他 three.js 组件，如控件（controls）、加载器（loaders）和后期处理效果（post-processing effects）则属于 [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm addons/] 目录的一部分。附加组件无需单独安装，但需要单独导入。

下面的示例展示了如何导入 three.js 的 [page:OrbitControls] 和 [page: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。这些项目需要单独安装，请参见 [link:#manual/zh/introduction/Libraries-and-Plugins 库和插件]。

## 下一步

是时候开始[link:#manual/zh/introduction/Creating-a-scene 创建一个场景]了。