第02章 环境搭建与快速开始

2.1 环境要求

在开始之前，请确保你的开发环境满足以下要求：

提示：Vite 8.x 对 Node 版本有较高要求，建议使用 Node 20 或更高版本。可以使用 node -v 检查当前版本。

2.2 获取项目

2.2.1 克隆项目

git clone https://github.com/znlgis/map-360-demo.git
cd map-360-demo

2.2.2 安装依赖

npm install

该命令会根据 package.json 安装所有依赖，包括 Vue、Vite、TypeScript、Photo Sphere Viewer 相关插件和 Leaflet。

2.3 启动开发服务器

npm run dev

启动后默认访问 http://localhost:5173，Vite 会提供热更新（HMR）功能，修改代码后页面自动刷新。

2.4 常用命令

package.json 中定义了以下脚本：

2.4.1 生产构建

npm run build

该命令会先执行 vue-tsc -b 进行类型检查，再执行 vite build 进行生产构建，最终产物输出到 dist/ 目录。

2.4.2 预览生产构建

npm run preview

在本地预览生产构建产物，验证构建结果是否正确。

2.5 快速体验

启动开发服务器后，你可以体验以下功能：

1. 浏览全景：拖拽旋转视角，滚轮缩放，点击全屏按钮
2. 切换场景：顶部下拉选择场景，或点击全景/地图中的绿色「跳转标记」（➜）直接切换
3. 添加标记：点击「添加标记」进入添加模式 → 点击全景图空白处（或直接点击右下角地图精确定位）→ 出现红色脉冲预览 pin → 填写名称与描述确认
4. 编辑标记：底部列表悬停标记行，点击 ✎ 按钮修改
5. 查找标记：底部列表搜索框按名称/描述过滤
6. 导入导出：底部列表「导出」下载 JSON；「导入」选择 JSON 文件合并标记
7. 删除/恢复：悬停标记行点击 ✕ 删除；「恢复默认」一键还原预设标记

2.6 常见问题

2.6.1 全景图片加载失败

全景图片与地图瓦片均来自公共资源（PSV 官方 CDN / OpenStreetMap），需要联网访问。如果图片加载失败，请检查网络连接。

2.6.2 端口被占用

如果 5173 端口被占用，Vite 会自动切换到其他端口，或使用 --port 参数指定：

npm run dev -- --port 8080

2.6.3 Node 版本过低

如果安装依赖或启动时提示 Node 版本过低，请升级 Node.js 到 20+ 版本，或使用 nvm 切换版本。

2.7 下一步

环境搭建完成后，进入 第03章 项目结构解析 了解项目的整体结构。