Web 图形与 3D / 系统课时

Vite 初始化 Three.js 工程

Vite 初始化 Three.js 工程

从空目录创建 Vite 原生 JavaScript 工程,安装 three,并让浏览器显示持续旋转的彩色立方体。完成后可以通过开发服务器即时查看修改,使用构建命令生成静态文件,再预览生产产物,形成可继续开发产品展示页的最小工程。

学习目标

  • 检查 Node.js 与 npm,使用 Vite 的 vanilla 模板创建项目。
  • 在 ES 模块入口导入 Three.js,完成场景、相机与渲染器的最小联动。
  • 运行开发、构建和预览命令,判断各阶段是否成功。

检查 Node.js 环境

打开系统终端,确认 Node.js 与 npm 已经安装。当前 Vite 要求 Node.js 20.19+ 或 22.12+;新建项目建议使用受支持的 Node.js LTS 版本。不要仅凭 node 命令存在就认定版本满足要求。

bash
node --version
npm --version

预期输出(版本号仅为示例):

text
v22.12.0
10.9.0

如果提示命令不存在,先安装 Node.js 并重启终端;如果 Vite 提示 EBADENGINE 或 Node.js 版本不足,升级 Node.js 后重新安装依赖。项目执行全程使用同一个终端环境,避免不同终端引用不同的 Node.js。

创建项目并安装 three

用 Vite 的原生 JavaScript 模板初始化工程,不引入 React 或 Vue。命令中的 -- --template vanilla 会把模板选项传给 create-vite;three 是运行时依赖,应该通过 npm 安装,而不是从网页复制脚本标签。

bash
npm create vite@latest threejs-showroom -- --template vanilla
cd threejs-showroom
npm install
npm install three

预期结果:项目根目录出现 index.html、package.json、src/main.js,安装后出现 node_modules 和 package-lock.json。package.json 的 dependencies 中应有 three,devDependencies 中应有 vite,版本号由安装时的仓库状态决定。

Vite 把根目录的 index.html 作为 HTML 入口。默认 vanilla 模板包含 id="app" 的挂载元素,并通过 type="module" 加载 /src/main.js。后续代码保留这两个约定即可,不必自己添加 CDN 地址。

用模块入口绘制立方体

用以下完整代码替换 src/main.js。Scene 保存物体,PerspectiveCamera 决定视角,WebGLRenderer 在页面的 Canvas 上绘制;MeshNormalMaterial 不需要光源,适合首次验证。入口直接导入 three,依赖解析由 Vite 完成。

js
import * as THREE from 'three'

const app = document.querySelector('#app')
if (!app) throw new Error('缺少 #app 容器')
app.replaceChildren()
document.body.style.margin = '0'

const scene = new THREE.Scene()
scene.background = new THREE.Color(0x0f172a)
const camera = new THREE.PerspectiveCamera(
  60,
  window.innerWidth / window.innerHeight,
  0.1,
  100
)
camera.position.z = 3

const renderer = new THREE.WebGLRenderer({ antialias: true })
// 限制高像素密度屏幕的渲染开销
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))
renderer.setSize(window.innerWidth, window.innerHeight)
app.appendChild(renderer.domElement)

const geometry = new THREE.BoxGeometry(1, 1, 1)
// 法线材质不依赖场景灯光
const material = new THREE.MeshNormalMaterial()
const cube = new THREE.Mesh(geometry, material)
scene.add(cube)

renderer.setAnimationLoop(() => {
  cube.rotation.x += 0.005
  cube.rotation.y += 0.01
  renderer.render(scene, camera)
})

// 窗口变化时同步更新投影矩阵与画布
window.addEventListener('resize', () => {
  camera.aspect = window.innerWidth / window.innerHeight
  camera.updateProjectionMatrix()
  renderer.setSize(window.innerWidth, window.innerHeight)
})

预期结果:浏览器画面为深蓝背景、居中的彩色旋转立方体;改变浏览器窗口尺寸后,立方体形状不会被拉伸。由于此文件已不再导入模板的 style.css,无需额外清除模板的默认页面样式。

启动开发服务器并验证修改

在项目根目录运行开发命令,不要直接双击 index.html:浏览器独立打开文件时无法像 Vite 一样解析 from 'three' 这样的包导入路径。

bash
npm run dev

预期结果:终端显示 Local: http://localhost:<PORT>/,默认端口通常是 5173;如果端口已被占用,以终端给出的实际地址为准。打开该地址应看到旋转立方体,开发者工具 Console 不应出现模块解析错误。

把 cube.rotation.y += 0.01 改为 cube.rotation.y += 0.03 并保存,观察立方体转速是否提高,从而确认开发时的自动更新有效。完成后按 Ctrl+C 停止开发服务器,或另开终端执行构建。

验证构建和生产预览

Vite 的 build 脚本会处理模块依赖并输出可部署的静态资源;preview 用于在本地检查刚生成的产物,不等于正式部署。两条命令都应在 threejs-showroom 根目录执行。

bash
npm run build
npm run preview

预期结果:构建成功后出现 dist/index.html 和 dist/assets/ 下的打包资源;预览服务在终端列出访问地址,默认通常为 http://localhost:4173/。浏览器打开预览地址仍能看到旋转立方体。修改源代码后需要重新执行 npm run build,预览才会反映新产物。

按错误现象定位问题

如果浏览器白屏,先打开开发者工具的 Console,再回到终端确认命令成功:Failed to resolve import "three" 通常说明没有在正确的项目目录执行 npm install three;#app 找不到则检查 index.html 中的容器是否被删除,以及脚本路径是否仍为 /src/main.js。

如果出现 WebGL 上下文创建失败,应确认浏览器支持并启用了 WebGL2、硬件加速可用。构建成功并不保证设备能渲染 WebGL,因此最终验收要同时检查开发地址和预览地址。准备发布时上传的是 dist/ 的构建结果,而不是 src/ 或 node_modules/。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

Vite 初始化 Three.js 工程

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通