第01章：Photo-Sphere-Viewer 项目全景与学习路线

1.1 Photo-Sphere-Viewer 是什么

Photo-Sphere-Viewer（后文简称 PSV）是一个基于 Three.js 的开源 JavaScript 库，专门用于在网页上展示 360° 球形全景图。它让开发者只需要寥寥数行代码，就能在浏览器中呈现一个可交互的、功能完备的全景查看器——支持鼠标拖拽旋转、滚轮缩放、键盘导航、触摸手势，以及丰富的标记与插件扩展。

PSV 的起源可以追溯到 JeremyHeleine 创建的原始项目，现在由法国开发者 Damien Sorel（GitHub ID: mistic100）主导维护。项目托管在 GitHub，截至最新版本已获得超过 2,300 颗 Star，采用 MIT 许可协议，允许商业和非商业用途的自由使用、修改和分发。

Photo-Sphere-Viewer 是”基于 Three.js 的开源 360° 全景展示引擎 + 插件生态”——代码结构清晰，插件体系完善，是 Web 全景开发领域社区活跃度最高、功能最完整的解决方案之一。

关键信息速览：

v5 是 PSV 的一次重大重构。相比 v4，整个项目迁移为 TypeScript 编写，采用 Turborepo 管理的 monorepo 多包结构，将核心查看器与各个适配器/插件拆分为独立的 npm 包（@photo-sphere-viewer/core + 17 个子包），构建工具也从 Webpack 切换到了基于 esbuild 的 tsup，大幅提升了开发和构建速度。

1.2 为什么要学习 Photo-Sphere-Viewer

1.2.1 全景技术的广泛应用

360° 全景图和虚拟现实正在重塑用户与数字内容的交互方式。以下领域的全景应用已经相当成熟：

• 房地产：VR 看房、楼盘全景展示，让客户足不出户就能”走进”样板间
• 旅游与酒店：景区导览、酒店客房预览，提升预订转化率
• 电商与零售：商品 360° 旋转展示、店铺虚拟逛店，增强购物体验
• 教育：虚拟实验室、历史遗址重现、地理教学中的地貌展示
• 虚拟展会：线上展厅、产品发布会、远程会议中的沉浸式展示
• 汽车行业：车内 360° 内饰浏览、外观交互展示
• 文化遗产：博物馆数字展厅、文物全景记录与数字化保护

1.2.2 主流全景方案对比

在 Web 全景领域，PSV 并非唯一的方案。下表从多个维度对比了当前主流的开源全景方案：

PSV 的核心优势在于：

1. API 友好度最高：声明式配置 + 事件驱动的编程模型，对于前端开发者几乎没有门槛
2. 插件体系完善：标记、虚拟漫游、陀螺仪、VR、地图集成等常见需求都有对应插件，且接口统一
3. 文档质量高：官方文档覆盖了每个插件的 API、配置项和代码示例
4. TypeScript 原生支持：从 v5 起全量 TypeScript，类型提示完整，IDE 体验极佳
5. 社区活跃：2,300+ Star、频繁的版本迭代，遇到问题更容易找到答案

1.2.3 学完能掌握什么

学习 PSV 不仅仅是学会一个库的用法，更是一次对 Web 3D 和前端工程化的深度实践：

• Web 3D 渲染基础：理解 Three.js 的 Scene / Camera / Renderer 模型，掌握纹理贴图、几何体、材质系统
• 全景图格式与投影：等距柱状投影（Equirectangular）、立方体贴图（Cubemap）、双鱼眼（Dual Fisheye）、分块加载（Tiles）——各种全景图格式的原理和适配
• 插件架构设计：PSV 的插件系统是一个优秀的 微内核 + 插件 设计案例，学习它有助于理解大型前端项目如何通过插件化保持可扩展性和可维护性
• Monorepo 工程化实践：Turborepo 多包仓库管理、共享配置、独立版本发布
• 前端性能优化：全景纹理的延迟加载、视锥体裁剪、事件节流等实际优化策略

1.3 核心功能总览

PSV v5 的功能体系可以归纳为以下八大模块。每个模块都有对应的核心类或插件实现：

1.3.1 全景图加载与适配

PSV 通过适配器（Adapter）机制支持多种全景图格式，每种适配器负责解析特定格式并构造 Three.js 场景：

此外，v5 还内置了对裁剪全景图（Cropped Panorama）的功能支持，可通过 croppedXxx 配置直接在标准适配器上使用。

1.3.2 交互控制

PSV 提供了完整的用户交互能力，所有交互行为均可通过配置精确控制：

• 鼠标拖拽旋转：支持灵敏度、阻尼系数、反转方向等配置
• 滚轮缩放：可配置缩放范围、步长、动画速度
• 键盘导航：方向键旋转、+/- 缩放，支持自定义键位映射
• 触摸手势：单指拖拽、双指缩放/旋转（pinch），移动端体验丝滑
• 移动惯性：释放鼠标/手指后带有自然衰减的惯性动画（可配置持续时间和减速系数）
• 自动旋转：v5 中作为独立插件 @photo-sphere-viewer/autorotate-plugin，支持键盘/鼠标交互时自动暂停

1.3.3 标记系统（MarkersPlugin）

标记系统是 PSV 最核心、最强大的功能模块之一，通过 @photo-sphere-viewer/markers-plugin 提供：

• 2D 标记：始终面向相机、保持在屏幕平面上的标记，适合文字标签、图标按钮
• 3D 标记：附着在全景球面上、随视角变化的标记，适合标注空间中的具体位置
• HTML 标记：可嵌入任意 HTML 内容的标记，支持 CSS 样式和事件绑定
• SVG 形状：直接在全景上绘制 SVG 图形——
  • 矩形 (svgRect)
  • 圆形 (svgCircle)
  • 多边形 (svgPolygon)
  • 折线 (svgPolyline)
• Tooltip：每个标记支持弹出提示框，可自定义内容和样式
• 动画：标记支持显示/隐藏动画、缩放弹跳效果

1.3.4 虚拟漫游（VirtualTourPlugin）

@photo-sphere-viewer/virtual-tour-plugin 将多个全景节点连接成可导航的虚拟空间：

• 多节点链接：在不同全景场景之间建立跳转链接
• GPS 定位：每个节点支持经纬度坐标，可在地图上可视化
• 2D / 3D 箭头：在场景中渲染导航箭头，引导用户前往下一个节点
• 过渡动画：节点切换时的平滑过渡效果
• 预加载：提前加载下一个节点的纹理，减少等待时间

1.3.5 视频全景（VideoPlugin）

@photo-sphere-viewer/video-plugin 支持 360° 视频的播放与交互：

• 支持 MP4 / WebM 等常见视频格式
• 完整的播放控制：播放/暂停、进度条、音量调节
• 多分辨率支持（自适应码率）

1.3.6 移动端优化

• 陀螺仪插件 (@photo-sphere-viewer/gyroscope-plugin)：利用设备陀螺仪实现”移动设备 = 取景框”的自然交互
• VR 插件 (@photo-sphere-viewer/stereo-plugin)：左右分屏的 VR 立体视图，配合 Cardboard 等设备使用
• 触摸优化：原生 touch 事件处理，支持多点触控

1.3.7 地图与导航

• 指南针 (@photo-sphere-viewer/compass-plugin)：在界面上显示方向指示，随视角旋转
• 地图集成：可通过 @photo-sphere-viewer/map-projection-plugin 或自定义实现将全景视角投影到平面地图上

1.3.8 扩展与集成

• 插件体系：统一的 AbstractPlugin 基类，标准化的生命周期（init / destroy / setOption），类型安全的插件 API
• 自定义按钮：通过 navbar 配置添加自定义工具栏按钮
• SCSS 主题：通过 SASS 变量定制外观风格
• 事件系统：基于原生 EventTarget API，完全继承浏览器事件机制
• 框架集成：官方提供示例展示如何在 React、Vue 中封装 PSV 组件

1.4 技术架构

1.4.1 分层架构

PSV 采用了清晰的分层设计，从上到下依次为：

┌─────────────────────────────────────────────┐
│                  Viewer                      │  ← 顶层 API，用户直接交互
│         (核心查看器，组合所有子系统)            │
├──────────┬──────────┬──────────┬─────────────┤
│  Navbar  │  Panel   │ Plugins  │   Adapter   │  ← 功能层
│ (工具栏)  │ (面板)    │ (插件)    │  (适配器)    │
├──────────┴──────────┴──────────┴─────────────┤
│              Three.js Renderer               │  ← 渲染层
│      (Scene + Camera + WebGLRenderer)        │
├──────────────────────────────────────────────┤
│                Cache / Utils                  │  ← 基础设施层
│      (纹理缓存、事件工具、数据类型等)            │
└──────────────────────────────────────────────┘

• Viewer：核心控制器，持有所有子系统引用，提供公开 API，协调生命周期
• Adapter：负责根据全景图格式构造 Three.js 场景（几何体 + 材质 + 纹理），将不同格式统一为 Viewer 可消费的内部表示
• Plugin：所有扩展功能的基类，通过依赖注入获得 Viewer 引用，在特定生命周期阶段注册行为
• Navbar：可定制的工具栏组件，支持按钮注册、分组、自适应布局
• Panel：侧边面板组件，供插件（如设置面板、图库列表）使用
• Cache：纹理缓存层，避免重复加载相同资源

1.4.2 核心依赖与开发栈

1.4.3 包体系

v5 的 monorepo 结构将功能拆分为 1 个核心包 + 17 个子包：

@photo-sphere-viewer/
├── core                          # 核心：Viewer、事件系统、类型定义、UI 组件
├── equirectangular-adapter       # 等距柱状投影适配器
├── cubemap-adapter               # 立方体贴图适配器
├── equirectangular-tiles-adapter # 分块等距柱状投影适配器
├── cubemap-tiles-adapter         # 分块立方体贴图适配器
├── little-planet-adapter         # 小行星投影适配器
├── markers-plugin                # 标记系统
├── virtual-tour-plugin           # 虚拟漫游
├── gallery-plugin                # 图库/画廊
├── video-plugin                  # 视频全景
├── gyroscope-plugin              # 陀螺仪
├── stereo-plugin                 # VR 立体视图
├── autorotate-plugin             # 自动旋转
├── compass-plugin                # 指南针
├── map-projection-plugin         # 地图投影联动
├── resolution-plugin             # 分辨率控制
├── settings-plugin               # 设置面板
└── shared-utils                  # 共享工具函数

1.4.4 事件系统

v5 最大的一项架构变更是废弃 uEvent，全面采用浏览器原生 EventTarget API：

// v4 (uEvent) —— 已废弃
viewer.on('click', (e, data) => { /* ... */ });

// v5 (EventTarget) —— 当前标准
viewer.addEventListener('click', (event) => {
  // event 是标准的 CustomEvent，data 在 event.detail 中
  const data = event.detail;
});
viewer.removeEventListener('click', handler);
viewer.dispatchEvent(new CustomEvent('custom-event', { detail: { ... } }));

这一变更使得 PSV 的事件系统与浏览器标准完全一致，不再需要学习任何第三方事件库的 API。

1.5 仓库结构鸟瞰

PSV 的 monorepo 仓库结构如下：

Photo-Sphere-Viewer/
├── packages/                     # 所有子包的源码
│   ├── core/                     #   @photo-sphere-viewer/core
│   │   ├── src/
│   │   │   ├── Viewer.ts         #     核心查看器类
│   │   │   ├── services/         #     内部服务（渲染器、纹理加载等）
│   │   │   ├── components/       #     Navbar、Panel、Notification 等 UI 组件
│   │   │   ├── buttons/          #     内置按钮实现
│   │   │   ├── events/           #     事件类型定义
│   │   │   ├── utils/            #     工具函数
│   │   │   ├── styles/           #     SCSS 样式文件
│   │   │   └── data/             #     常量与枚举
│   │   └── package.json
│   ├── equirectangular-adapter/  #   等距柱状投影适配器
│   ├── cubemap-adapter/          #   立方体贴图适配器
│   ├── markers-plugin/           #   标记系统插件
│   ├── virtual-tour-plugin/      #   虚拟漫游插件
│   ├── ...                       #   其余 14 个子包
│   └── shared-utils/             #   共享工具包
├── examples/                     # 示例页面（按功能分类）
│   ├── basic/                    #   基础全景查看（各适配器示例）
│   ├── markers/                  #   标记系统示例
│   ├── virtual-tour/             #   虚拟漫游示例
│   ├── video/                    #   视频全景示例
│   └── ...
├── docs/                         # 官方文档（VitePress 构建）
│   ├── guide/                    #   指南文档
│   ├── plugins/                  #   插件文档
│   └── api/                      #   API 参考
├── website/                      # 官方网站（已迁移至 docs/ 目录统一管理）
├── scripts/                      # 构建与发布脚本
├── turbo.json                    # Turborepo 配置
├── tsconfig.base.json            # 共享 TypeScript 配置
└── package.json                  # 根 package.json（workspaces 定义）

核心源文件入口是 packages/core/src/Viewer.ts，这里是理解整个系统运作的最佳起点。Viewer 类管理着：

• Renderer（Three.js 场景、相机、WebGL 渲染器）
• TextureLoader（纹理加载与缓存）
• Navbar（工具栏）
• Panel（侧边面板）
• Plugin 注册表（所有已注册的插件实例）
• 事件分发（EventTarget 的实现）
• 动画循环（requestAnimationFrame 驱动的渲染循环）

1.6 与生态中其他工具的关系

1.6.1 Marzipano

Marzipano 是 Google 开发的全景查看器，特点是不依赖 Three.js，使用自研的 WebGL 渲染引擎。它在性能优化方面做得很极致（比如瓦片加载策略），但插件生态很少，文档相对简略，适合只需要基本全景展示、追求极致性能的场景。PSV 相比之下功能更全面、扩展性更强。

1.6.2 Pannellum

Pannellum 是一个轻量级全景查看器，同样不依赖 Three.js。它的最大优势是极低的使用门槛——只需写一段 HTML 配置即可嵌入全景图，无需编写 JavaScript。但它的扩展能力有限，标记系统也比 PSV 简单得多。适合”只需展示”的场景，不适合需要深度交互的项目。

1.6.3 A-Frame

A-Frame 是 Mozilla 推出的 WebVR 框架，基于 Three.js，使用声明式的 HTML 标签构建 3D/VR 场景。它的定位比 PSV 更”底层”——不仅限于全景图，而是整个 VR/AR 场景的构建框架。如果项目涉及复杂的 3D 场景、用户自主建模、多人协作等需求，A-Frame 可能更合适；如果核心需求就是全景展示 + 标记 + 漫游，PSV 的上手速度远快于 A-Frame。

1.6.4 Krpano

Krpano 是专业级的商业全景引擎，功能极为强大（支持各种投影、热点编辑、皮肤定制、脚本编程），但它是商业软件，需要购买许可证，且 API 较为复杂，学习曲线陡峭。PSV 可以视为 Krpano 的开源替代方案中功能最接近的一个。

1.6.5 PSV 的生态位

综合来看，PSV 在 Web 全景领域占据了一个最佳平衡点：

比 Pannellum 更强大，比 Marzipano 更易扩展，比 A-Frame 更专注全景，比 Krpano 更开放且免费。

如果你的项目满足以下特征之一，PSV 就是最合适的选择：

• 需要标记 + 漫游 + 视频 + 地图等多功能组合
• 需要与现有前端框架（React/Vue）深度集成
• 团队使用 TypeScript，需要完整的类型安全
• 需要自定义 UI 或开发专属插件
• 希望从开源项目中学习 Web 3D 和插件架构

1.7 学习路线建议

根据读者的不同背景和目标，本教程设计了三条学习路径：

路径 A：内容创作者 / 全景摄影师

目标：快速上手，能独立搭建全景展示页面，添加标记和简单的虚拟漫游。

预计耗时：按顺序阅读并动手实践，约 15-20 小时。

路径 B：Web 前端开发者

目标：深入理解 PSV 的架构原理、插件系统和 Three.js 应用，具备二次开发能力。

预计耗时：按顺序阅读并动手实践，约 30-40 小时。

路径 C：产品经理 / 技术负责人

目标：评估 PSV 是否适合当前项目，了解技术栈、能力边界和集成成本。

预计耗时：快速浏览关键章节 + 运行示例，约 3-5 小时。

1.8 v4 到 v5 的重要变更

如果你之前使用过 PSV v4 或者正在阅读基于 v4 的旧教程，下表列出了从 v4 迁移到 v5 需要关注的关键变更：

1.8.1 坐标系统重命名的原因

v5 将 longitude / latitude 重命名为 yaw / pitch，主要是因为这两个词更准确地描述了视角方向而非地理坐标。在 3D 图形学和航空领域中：

• Yaw (偏航角)：绕竖直轴（Y 轴）旋转，范围 [−π, π]，控制水平左右旋转
• Pitch (俯仰角)：绕水平轴（X 轴）旋转，范围 [−π/2, π/2]，控制上下旋转
• Roll (滚转角)：PSV 在全景查看器中不使用

1.8.2 迁移注意事项

1. 事件监听：在所有使用 on() / off() 的地方改为标准的 addEventListener() / removeEventListener()；事件数据从回调参数变为 event.detail
2. 坐标属性：全局搜索替换 longitude → yaw，latitude → pitch
3. 插件分离：如果你想使用自动旋转功能，记得先安装 @photo-sphere-viewer/autorotate-plugin 并注册
4. 类型路径：类型定义从集中导出变为按包导出，IDE 的自动导入通常能正确处理

1.9 推荐资料

官方资源

Three.js 学习资源

PSV 的核心渲染能力完全依赖 Three.js，要深入理解 PSV 的内部机制，建议同时学习以下 Three.js 概念：

相关社区与项目

1.10 本章小结

本章从”是什么”和”为什么”两个维度出发，为读者建立起了对 Photo-Sphere-Viewer 的整体认知：

1. 产品层面：PSV 是一个基于 Three.js 的开源全景查看器，支持等距柱状、立方体、鱼眼等多种全景格式，提供标记、漫游、视频、陀螺仪等丰富的插件生态，是 Web 全景领域功能最全面、API 最友好的开源方案
2. 技术层面：v5 采用 TypeScript + SASS + Turborepo monorepo 架构，1 个核心包 + 17 个子包，基于原生 EventTarget 事件系统，ESM 优先输出
3. 生态定位：在”功能完整性 vs 上手难度”的坐标系中，PSV 占据了最佳平衡点——比轻量方案更强大，比重型框架更专注，比商业方案更开放
4. 学习路线：针对不同背景的读者提供了三条推荐路径，可以根据自身需求灵活选择

从下一章开始，我们将进入真正的动手环节——搭建开发环境，写出第一个全景应用，并看到 360° 全景图在浏览器中旋转起来的那一刻。