# Установка ([name])

Вы можете установить three.js с помощью [link:https://www.npmjs.com/ npm] и современных инструментов сборки или быстро начните работу со статического хостинга или CDN. Для большинства пользователей установка из npm является лучшим выбором.

Что бы вы ни выбрали, будьте последовательны и импортируйте все файлы из одной и той же версии библиотеки. Смешивание файлов из разных источников может привести к включению дублирующегося кода или даже к неожиданной поломке приложения.

Все способы установки three.js зависят от модулей ES (см. [link:https://eloquentjavascript.net/10_modules.html#h_hF2FmOVxw7 Eloquent JavaScript: ECMAScript Modules]), которые позволяют включать в конечный проект только те части библиотеки, которые необходимы.

## Установка из npm

Чтобы установить [link:https://www.npmjs.com/package/three three] модуль npm, откройте окно терминала в папке вашего проекта и запустите:

`npm install three`

Пакет будет загружен и установлен. Когда вы будете готовы импортировать его в свой код:

`// Вариант 1: Импортируйте весь three.js основная библиотека. import * as THREE from 'three'; const scene = new THREE.Scene(); // Вариант 2: Импортируйте только те детали, которые вам нужны. import { Scene } from 'three'; const scene = new Scene();`

При установке из npm вы почти всегда будете использовать какой-либо [link:https://eloquentjavascript.net/10_modules.html#h_zWTXAU93DC bundling tool], чтобы объединить все пакеты, необходимые вашему проекту, в один файл JavaScript. В то время как любой современный пакет JavaScript можно использовать с three.js , самым популярным выбором является [link:https://webpack.js.org/ webpack].

Не ко всем функциям можно получить доступ непосредственно через модуль three (также называемый "голым импортом"). Другие популярные части библиотеки, такие как элементы управления, загрузчики и эффекты постобработки, должны быть импортированы из подпапки [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm]. Чтобы узнать больше, смотрите Примеры ниже.

Узнайте больше о модулях npm по ссылке [link:https://eloquentjavascript.net/20_node.html#h_J6hW/SmL/a Eloquent JavaScript: Installing with npm](Выразительный JavaScript: Установка с помощью npm).

## Установка с CDN или статического хостинга

В three.js библиотеку можно использовать без какой-либо системы сборки, либо загрузив файлы на свой собственный веб-сервер, либо используя существующий CDN. Поскольку библиотека полагается на модули ES, любой скрипт, который ссылается на нее, должен использовать type="module", как показано ниже. Также требуется определить карту импорта, которая разрешает пустой модуль, указанный как `three`.

`<script type="importmap"> { "imports": { "three": "https://unpkg.com/three@<version>/build/three.module.js" } } </script> <script type="module"> import * as THREE from 'three'; const scene = new THREE.Scene(); </script>`

## Дополнения

Ядро three.js сосредоточен на наиболее важных компонентах 3D-движка. Многие другие полезные компоненты, такие как элементы управления, загрузчики и эффекты постобработки, являются частью каталога [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm]. Они называются "дополнениями"(addons) (ранее назывались "примерами"(examples)), потому что, хотя вы можете использовать их в готовом виде, они также предназначены для ремиксов и кастомизации. Эти компоненты всегда синхронизируются с основной библиотекой, в то время как аналогичные пакеты сторонних разработчиков в npm поддерживаются разными пользователями и могут быть устаревшими.

Дополнения не нужно устанавливать отдельно, но их нужно импортировать отдельно. Если three.js был установлен с помощью npm, вы можете загрузить компонент [page:OrbitControls](Управление орбитой) с помощью:

`import { OrbitControls } from 'three/addons/controls/OrbitControls.js'; const controls = new OrbitControls( camera, renderer.domElement );`

Если three.js был установлен с CDN, используйте тот же код, но с `three/addons/` в карте импорта.

`<script type="importmap"> { "imports": { "three": "https://unpkg.com/three@<version>/build/three.module.js", "three/addons/": "https://unpkg.com/three@<version>/examples/jsm/" } } </script> <script type="module"> import * as THREE from 'three'; import { OrbitControls } from 'three/addons/controls/OrbitControls.js'; const controls = new OrbitControls( camera, renderer.domElement ); </script>`

Важно, чтобы все файлы использовали одну и ту же версию. Не импортируйте разные дополнения(addons) из разных версий и не используйте дополнения(addons) из версии, отличной от three.js самой библиотека.

## Совместимость

### CommonJS импорт

В то время как большинство современных пакетов JavaScript теперь поддерживают модули по умолчанию, некоторые старые инструменты сборки могут этого не делать. В этих случаях вы, вероятно, можете настроить пакет для подключения модулей ES: [link:http://browserify.org/ Browserify] просто нужен плагин [link:https://github.com/babel/babelify babelify] , как пример.

### Node.js

Так как three.js создан для Интернета, он зависит от браузера и DOM API, которые не всегда существуют в Node.js. Некоторые из этих проблем могут быть решены с помощью прослоек, таких как [link:https://github.com/stackgl/headless-gl headless-gl], или путем замены компонентов, таких как [page:TextureLoader], пользовательскими альтернативами. Другие API-интерфейсы DOM могут быть глубоко переплетены с использующим их кодом, и обойти их будет сложнее. Мы приветствуем простые и поддерживаемые предложения `pull requests` для улучшения поддержки Node.js, но рекомендуем сначала открыть `issue`(вопрос), чтобы обсудить ваши улучшения.

Обязательно добавьте `{ "type": "module" }` в свой `package.json`, чтобы включить модули ES6 в ваш проект.