Three.js Wiki

简体中文

English

简体中文

English

Appearance

安装 ​

项目结构 ​

每个 three.js 项目至少需要一个 HTML 文件来定义网页，以及一个 JavaScript 文件来运行你的 three.js 代码。下面的结构和命名选择不是必需的，但为了保持一致性，本指南将始终使用这些名称。

  • index.html
    <!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="utf-8">
    <title>我的第一个 three.js 应用</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/ 文件夹有时也被称为"静态"文件夹，因为它包含的文件会原样推送到网站。通常纹理、音频和 3D 模型会放在这里。

现在我们已经设置了基本的项目结构，我们需要一种方法在本地运行项目并通过 Web 浏览器访问它。安装和本地开发可以通过 npm 和构建工具完成，也可以通过 CDN 导入 three.js。下面的章节将解释这两种选项。

选项 1：使用 NPM 和构建工具安装 ​

开发 ​

从 npm 包注册表安装并使用构建工具是大多数用户的推荐方法——你的项目需要的依赖越多，就越可能在静态托管无法轻易解决的问题上遇到困难。使用构建工具，导入本地 JavaScript 文件和 npm 包应该开箱即用，无需 import maps。

  1. 安装 Node.js。我们需要它来加载管理依赖项和运行我们的构建工具。

  2. 在项目文件夹中使用终端安装 three.js 和构建工具 Vite。Vite 将在开发期间使用，但它不是最终网页的一部分。如果你更喜欢使用其他构建工具，那也没关系——我们支持可以导入 ES Modules的现代构建工具。

    # three.js
npm install --save three

# vite
npm install --save-dev vite

    安装为我的项目添加了 node_modules/ 和 package.json。它们是什么？

    npm 使用 package.json 来描述你安装的每个依赖项的版本。如果你有其他人一起在这个项目上工作，他们只需运行 npm install 就可以安装每个依赖项的原始版本。如果你使用版本历史，请提交 package.json。

    npm 在新的 node_modules/ 文件夹中安装每个依赖项的代码。当 Vite 构建你的应用程序时，它会看到 'three' 的导入，并自动从该文件夹中提取 three.js 文件。node_modules/ 文件夹仅在开发期间使用，不应上传到你的 Web 托管提供商或提交到版本历史中。

    使用 jsconfig 或 tsconfig 改进你的编辑器自动完成

    在你的项目根目录中放置一个 jsconfig.json（或 TypeScript 项目的 tsconfig.json）。添加下面的配置有助于你的编辑器定位 three.js 文件以增强自动完成功能。

    {
  "compilerOptions": {
    // 其他选项...
    "paths": {
      "three/webgpu": ["node_modules/three/build/three.webgpu.js"],
      "three/tsl": ["node_modules/three/build/three.tsl.js"],
    },
  }
}

  3. 从你的终端运行：

    npx vite

    npx 是什么？

    npx 随 Node.js 一起安装，并运行像 Vite 这样的命令行程序，这样你就不必自己在 node_modules/ 中搜索正确的文件。如果你愿意，可以将 Vite 的常用命令放入 package.json:scripts列表中，并改用 npm run dev。

  4. 如果一切顺利，你会在终端中看到类似 http://localhost:5173 的 URL，并且可以打开该 URL 来查看你的 Web 应用程序。

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

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

生产 ​

稍后，当你准备好部署 Web 应用程序时，只需告诉 Vite 运行生产构建——npx vite build。应用程序使用的所有内容都将被编译、优化并复制到 dist/ 文件夹中。该文件夹的内容已准备好托管在你的网站上。

选项 2：从 CDN 导入 ​

开发 ​

不使用构建工具安装需要对上面给出的项目结构进行一些更改。

  1. 我们在 main.js 中从 'three'（一个 npm 包）导入了代码，Web 浏览器不知道这意味着什么。在 index.html 中，我们需要添加一个 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"。最新版本可以在 npm 版本列表中找到。

  2. 我们还需要运行一个本地服务器来在 Web 浏览器可以访问的 URL 上托管这些文件。虽然从技术上讲，你可以双击 HTML 文件并在浏览器中打开它，出于安全原因，我们将要实现的重要功能在以这种方式打开页面时不起作用。

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

    npx serve .

  3. 如果一切顺利，你会在终端中看到类似 http://localhost:3000 的 URL，并且可以打开该 URL 来查看你的 Web 应用程序。

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

许多其他本地静态服务器可用——一些使用不同的语言而不是 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+)

GUI ​

GUI 本地服务器作为计算机上的应用程序窗口运行，并且可能具有用户界面。

代码编辑器插件 ​

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

生产 ​

当你准备好部署 Web 应用程序时，将源文件推送到你的 Web 托管提供商——无需构建或编译任何内容。这种权衡的缺点是你需要小心保持 import map 与你的应用程序所需的任何依赖项（以及依赖项的依赖项！）更新。如果托管你依赖项的 CDN 暂时宕机，你的网站也将停止工作。

重要： 从同一版本的 three.js 和同一 CDN 导入所有依赖项。混合来自不同来源的文件可能会导致包含重复代码，甚至以意想不到的方式破坏应用程序。

插件 ​

开箱即用，three.js 包含 3D 引擎的基础。其他 three.js 组件——如控制器、加载器和后处理效果——是 addons/目录的一部分。插件不需要单独安装，但需要单独导入。

下面的示例展示了如何使用 OrbitControls 和 GLTFLoader 插件导入 three.js。如有必要，这也会在每个插件的文档或示例中提到。

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。这些需要单独安装。

下一步 ​

你现在准备好创建场景。

Copyright © 2026 LZUGIS