Vue 3 + Three.js 新手也能搞定的全景看房Demo：从一张图到可交互场景

Vue 3 + Three.js 全景看房实战：从零构建可交互3D场景

第一次接触3D网页开发时，我被那些酷炫的房地产网站震撼到了——手指轻轻滑动就能360°查看样板间，仿佛真的置身其中。作为Vue开发者，其实用Three.js实现这种效果比想象中简单得多。本文将带你从一张普通全景图开始，逐步构建完整的可交互看房场景，过程中会特别关注新手容易踩坑的细节。

1. 环境准备与项目初始化

在开始编写3D代码前，我们需要搭建好Vue 3的开发环境。推荐使用Vite创建项目，它能提供更快的构建速度和更好的开发体验：

npm create vite@latest vue3-threejs-panorama --template vue cd vue3-threejs-panorama npm install three @types/three

安装完成后，在src/components目录下新建PanoramaViewer.vue组件。这个组件将成为我们3D场景的容器。Three.js的基本架构包含三个核心对象：

• 场景(Scene)：所有3D对象的容器
• 相机(Camera)：观察场景的视角
• 渲染器(Renderer)：将3D场景绘制到2D屏幕

初始化这些对象的代码如下：

import * as THREE from 'three' import { onMounted } from 'vue' const scene = new THREE.Scene() const camera = new THREE.PerspectiveCamera( 75, // 视野角度 window.innerWidth / window.innerHeight, // 宽高比 0.1, // 近截面 1000 // 远截面 ) const renderer = new THREE.WebGLRenderer({ antialias: true }) onMounted(() => { renderer.setSize(window.innerWidth, window.innerHeight) document.getElementById('panorama-container')?.appendChild(renderer.domElement) })

2. 构建全景球体与材质贴图

全景看房的核心原理其实很简单：将全景图片贴在一个球体内表面，然后把相机放在球体中心。这样无论用户看向哪个方向，都能看到对应的墙面景象。

2.1 准备全景图片

选择全景图时需要注意：

• 图像必须是等距柱状投影格式（equirectangular）
• 建议分辨率至少8000×4000像素以保证清晰度
• 图片应无缝衔接，避免明显的拼接痕迹

将图片放在public/textures目录下，这样Three.js的TextureLoader可以直接加载。以下是创建球体和应用贴图的关键代码：

const sphereGeometry = new THREE.SphereGeometry( 500, // 半径 60, // 宽度分段数 40 // 高度分段数 ) const textureLoader = new THREE.TextureLoader() const texture = textureLoader.load('/textures/living-room.jpg') const sphereMaterial = new THREE.MeshBasicMaterial({ map: texture, side: THREE.BackSide // 关键！让材质渲染在球体内侧 }) const sphere = new THREE.Mesh(sphereGeometry, sphereMaterial) scene.add(sphere)

注意：如果遇到图片加载失败的问题，可能是CORS限制导致的。开发时可以将图片放在项目本地，上线后确保服务器配置了正确的CORS头。

2.2 优化材质渲染

默认的MeshBasicMaterial虽然简单，但缺乏真实感。我们可以改用MeshStandardMaterial并添加环境光：

const material = new THREE.MeshStandardMaterial({ map: texture, side: THREE.BackSide, roughness: 0.5, metalness: 0.1 }) const ambientLight = new THREE.AmbientLight(0xffffff, 0.6) scene.add(ambientLight)

3. 相机设置与交互控制

3.1 相机定位

将相机放置在球体中心，这是全景浏览的关键：

camera.position.set(0, 0, 0) // 设置初始视角稍微向下看，模拟人眼高度 camera.rotation.set(0, 0, 0)

3.2 添加轨道控制器

为了让用户能够自由查看全景，我们需要添加OrbitControls：

import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls' const controls = new OrbitControls(camera, renderer.domElement) controls.enableDamping = true // 添加阻尼效果使旋转更自然 controls.dampingFactor = 0.05 controls.screenSpacePanning = false // 限制只能在球体内观看 controls.minDistance = 0 controls.maxDistance = 0 // 禁止缩放移动

控制器的主要配置参数：

4. 动画循环与性能优化

Three.js需要通过持续渲染来保持场景动态更新。我们使用requestAnimationFrame创建动画循环：

function animate() { requestAnimationFrame(animate) controls.update() // 只在启用阻尼时需要 renderer.render(scene, camera) } animate()

针对移动设备的优化策略：

// 响应式调整渲染尺寸 window.addEventListener('resize', () => { camera.aspect = window.innerWidth / window.innerHeight camera.updateProjectionMatrix() renderer.setSize(window.innerWidth, window.innerHeight) }) // 根据设备像素比调整渲染精度 renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))

5. 常见问题排查

5.1 图片加载问题

如果遇到图片加载失败，可以添加错误处理：

textureLoader.load( '/textures/living-room.jpg', (texture) => { /* 成功回调 */ }, undefined, // 进度回调 (err) => { console.error('图片加载失败:', err) // 可以显示占位图或错误提示 } )

5.2 球体显示异常

如果看到球体显示不正常，检查以下几点：

1. 确认材质设置了side: THREE.BackSide
2. 检查相机是否确实位于球体中心(0,0,0)
3. 验证全景图是否为真正的等距柱状投影格式

5.3 性能问题

对于高分辨率全景图，可能会遇到性能瓶颈。可以考虑：

• 使用THREE.TextureLoader的loadAsync方法
• 实现图片渐进式加载
• 添加加载进度指示器

const loadingManager = new THREE.LoadingManager() loadingManager.onProgress = (url, loaded, total) => { console.log(`加载进度: ${loaded}/${total}`) } const textureLoader = new THREE.TextureLoader(loadingManager)

6. 进阶功能扩展

基础全景看房完成后，可以考虑添加以下增强功能：

6.1 热点标记

在特定位置添加可交互的热点：

// 创建热点精灵 const hotspotTexture = textureLoader.load('/textures/hotspot.png') const hotspotMaterial = new THREE.SpriteMaterial({ map: hotspotTexture }) const hotspot = new THREE.Sprite(hotspotMaterial) hotspot.position.set(0, 1, -3) // 放置在球体内某个位置 scene.add(hotspot) // 添加点击事件 window.addEventListener('click', (event) => { const mouse = new THREE.Vector2( (event.clientX / window.innerWidth) * 2 - 1, -(event.clientY / window.innerHeight) * 2 + 1 ) const raycaster = new THREE.Raycaster() raycaster.setFromCamera(mouse, camera) const intersects = raycaster.intersectObjects([hotspot]) if (intersects.length > 0) { console.log('热点被点击!') // 可以在这里触发信息弹窗或场景切换 } })

6.2 多场景切换

实现不同房间之间的过渡：

const rooms = { livingRoom: '/textures/living-room.jpg', bedroom: '/textures/bedroom.jpg', kitchen: '/textures/kitchen.jpg' } function switchRoom(roomName) { textureLoader.load(rooms[roomName], (newTexture) => { sphere.material.map = newTexture sphere.material.needsUpdate = true }) }

6.3 VR模式支持

通过WebXR API添加VR支持：

import { VRButton } from 'three/examples/jsm/webxr/VRButton' renderer.xr.enabled = true document.body.appendChild(VRButton.createButton(renderer)) function animate() { renderer.setAnimationLoop(() => { renderer.render(scene, camera) }) }

在实现这些功能时，记得测试不同设备的兼容性。Three.js的生态系统非常丰富，社区提供了大量示例和扩展库，遇到特殊需求时可以优先搜索现有解决方案。