@mrbaoquan/pano-cli

krpano 全景项目 CLI 工具 — 一键创建、构建、预览、发布全景漫游。

安装

npm install -g @mrbaoquan/pano-cli

更新

npm update -g @mrbaoquan/pano-cli

快速开始

# 1. 设置全局 krpano 路径（只需一次）
pano config --global --krpano "F:\path\to\krpano-1.20.12"

# 2. 创建项目
pano create my-tour

# 3. 将全景图 .jpg 放入 panoramas/ 下的子文件夹
#    如: panoramas/1-展厅A/  panoramas/2-展厅B/

# 4. 初始化工程（自动生成 vtour 目录、瓦片、XML）
cd my-tour
pano init

# 5. 本地预览
pano serve

所有命令支持在项目根目录或 vtour/ 目录下运行。

命令参考

pano create <name>

创建新全景项目骨架。

pano create my-tour

交互式提示输入 krpanotools 路径（已设置全局配置时回车即可使用全局值）。

创建的目录结构：

my-tour/
├── vtour/
│   ├── scenes.config.json    # 项目配置
│   ├── tour.xml              # krpano 主配置
│   ├── hotspots/             # 热点数据
│   └── WORKFLOW.md           # 工作流说明
├── panoramas/default/        # 全景图存放目录
├── .gitignore
└── README.md

pano init

首次初始化工程。自动完成：

• 扫描 panoramas/ 目录结构，同步 groups 到 scenes.config.json
• 调用 krpanotools 生成 vtour 基础文件（tour.html、skin/、plugins/）
• 复制内置 panohper UI 库
• 生成全部场景瓦片
• 生成 scenes.xml 和 skin/groups.xml

pano init

如已存在 tour.html 会跳过，需重新初始化请先删除相关文件。

pano sync [--force]

增量同步：扫描新增全景图、生成瓦片、更新 XML。

pano sync          # 仅处理新增图片
pano sync --force  # 强制重新生成所有瓦片

pano xml

仅更新 XML（不生成瓦片），适用于修改分组、标题后快速刷新。

pano xml

pano editor

进入编辑模式 — 将场景内联到 tour.xml，方便在 krpano 编辑器中拖拽热点。

pano editor

pano save

保存编辑模式中的热点修改，恢复 include 模式。

pano save

pano serve [-p <port>] [--edit]

启动本地 HTTP 预览服务器。

pano serve            # 默认端口 8090
pano serve -p 3000    # 指定端口
pano serve --edit     # 开启可视化编辑器
pano serve -e -p 8092 # 指定端口 + 编辑器

自动处理端口冲突（向上递增尝试）。

--edit 编辑模式 会在浏览器中注入编辑器面板，无需插件即可完成以下操作：

| 功能 | 说明 | | --- | --- | | 设为默认视角 | 保存当前视角（ath/atv/fov）到 sceneOverrides | | 热点管理 | 添加、编辑、删除场景热点（跳转/链接），保存至 hotspots/*.xml | | 排序管理 | 拖拽调整分组顺序及组内场景顺序，保存后重新生成 XML | | 生成 XML | 重新扫描并生成 scenes.xml + skin/groups_data.xml |

pano config [options]

查看或修改配置。

# 查看项目配置
pano config

# 设置项目 krpanotools 路径
pano config --krpano "F:\path\to\krpano"

# 设置全景图源目录
pano config --source "../panoramas"

# 查看全局配置
pano config --global

# 设置全局 krpanotools 路径（所有项目共享）
pano config --global --krpano "F:\path\to\krpano"

配置优先级：项目 scenes.config.json > 全局 ~/.pano-cli/config.json

pano clean

清除旧瓦片数据（已删除场景对应的 .tiles 目录）。

pano clean

pano publish [--oss]

打包发布文件。

pano publish         # 本地打包
pano publish --oss   # 瓦片路径指向 OSS

使用 --oss 时需在 scenes.config.json 中配置 ossBaseUrl 和 ossBucket。

pano dev <module> <path>

链接本地模块仓库进行开发（如 panohper UI 库）。

# 链接本地 panohper 仓库
pano dev panohper ../panohper

# 查看链接状态
pano dev --status

# 恢复为内置版本
pano dev --reset panohper

全局选项

| 选项 | 说明 | | --------------- | ---------------- | | -v, --verbose | 详细输出 | | -q, --quiet | 仅显示警告和错误 | | -V, --version | 显示版本号 |

scenes.config.json

{
  "krpanoToolsPath": "", // krpano 安装目录（可省略，使用全局配置）
  "panoSourceDir": "../panoramas", // 全景图源目录（相对 vtour/）
  "startScene": "展馆外观", // 默认起始场景名

  "ossBaseUrl": "https://xxx.com", // OSS 基础 URL（publish --oss 时使用）
  "ossBucket": "oss://bucket/path", // OSS 存储路径

  "groups": [
    // 分组（pano init/sync 自动生成；scenes 字段由排序编辑器写入）
    {
      "name": "展厅A",
      "folders": ["1-展厅A"],
      "scenes": ["panorama1", "panorama2"] // 可选：显式指定组内场景顺序
    }
  ],

  "sceneOverrides": {
    // 场景标题覆盖（也可在编辑器中通过「设为默认视角」写入 ath/atv/fov）
    "原始文件名": { "title": "自定义标题", "ath": 0, "atv": 0, "fov": 90 },
  },
}

groups 由 pano init / pano sync 自动扫描 panoramas/ 目录生成，无需手动配置。 文件夹名前缀数字会自动去除作为分组名（如 0-展馆外观 → 展馆外观）。 groups[].scenes 由排序编辑器（pano serve --edit）写入，控制该组内场景在 XML 中的顺序。

典型工作流

1. pano create my-tour          # 创建项目
2. 放入全景图到 panoramas/      # 按子文件夹分组
3. pano init                    # 初始化（生成瓦片 + XML）
4. pano serve --edit            # 预览 + 可视化编辑
   ├── 设为默认视角              # 调整每个场景的初始视角
   ├── 热点管理                  # 添加/编辑/删除跳转热点
   ├── 排序管理                  # 调整分组和场景顺序
   └── 生成 XML                 # 应用所有改动
5. pano publish                 # 打包发布

新增场景：放入图片 → pano sync 修改标题：编辑 sceneOverrides → pano xml 新增分组：在 panoramas/ 下创建文件夹并放入图片 → pano sync 调整顺序：pano serve --edit → 排序管理 → 保存 → 生成 XML

依赖

• Node.js >= 18
• krpano 1.20+（需自行购买，用于瓦片生成）

License

MIT