VOSviewer Online 本地版使用

本地部署的网页版 VOSviewer（https://github.com/neesjanvaneck/VOSviewer-Online）。
与桌面版（vosviewer-cli 技能）互补：桌面版负责批量出图/截图，网页版负责交互浏览。
数据格式相同（map + network 文本文件对，或 VOSviewer JSON），可直接消费主线技能产出的文件。

> 本技能全部步骤在 Windows + Git Bash + Node v22 实机验证（2026-10-28），安装目录
> .\VOSviewer-Online，服务端口 8600。
>
> v1.2.0 变更：JSON 章节补充桌面版方向——新增 scripts/json_to_map_network.py（JSON → map/network），
> 并写入实测结论：桌面版 1.6.21 的 -json 参数失效（exe/jar 一致、原生 -save_json 回灌也失败），
> 要让桌面版画 JSON 里的网络必须先转换。
>
> v1.1.0 变更：新增"JSON 网络文件格式"章节（结构、字段校验规则、与桌面版 -json 的差异）
> 与 scripts/map_network_to_json.py（map/network → 单文件 JSON），实机验证 156 节点/799 连线可正常加载。
>
> v1.0.1 变更：一键打开脚本统一为 Python 版 scripts/vosviewer-open.py（跨平台、纯标准库），
> 移除原 .cmd / .sh 版本，避免批处理转义与编码问题。

先决条件（安装前自查）

安装步骤

1) 获取源码

git clone --depth 1 https://github.com/neesjanvaneck/VOSviewer-Online "<安装目录>/VOSviewer-Online"

下载报错时不要反复重试，直接走国内镜像 zip 兜底（实测：系统代理返回
CONNECT tunnel failed, response 502，绕过代理直连返回
Failed to connect to github.com:443，两种失败都属此类）：

# ⚠️ 仓库默认分支是 master，不是 main——分支写错会拿到 14 字节的 "404: Not Found" 假 zip
curl -sL -o vosviewer.zip "https://gh-proxy.com/https://github.com/neesjanvaneck/VOSviewer-Online/archive/refs/heads/master.zip"
unzip -q vosviewer.zip && mv VOSviewer-Online-master VOSviewer-Online && rm vosviewer.zip

• 备用镜像：https://ghfast.top/https://github.com/...（同前缀用法）
• 不确定默认分支时先查：curl -sL "https://gh-proxy.com/https://api.github.com/repos/neesjanvaneck/VOSviewer-Online" | grep default_branch
• 判断技巧：下载的文件只有十几字节 = 镜像通了但路径/分支 404；连不上 = 镜像也挂了，换备用镜像

2) 安装依赖（务必用国内源）

cd "<安装目录>/VOSviewer-Online"
npm install --registry=https://registry.npmmirror.com

实测约 1021 个包、4–5 分钟。npm warn deprecated ... 为无害警告，可忽略。

3) 挂载数据目录（关键配置）

编辑 webpack.config.babel.js，把 devServer.static 指向用户当前工作目录下的
VOSviewer 导出目录（与主线技能 vosviewer-cli 的输出目录约定一致，
即 <工作目录>\vosviewer_out\——网络文件和截图统一放这里，不散落根目录）：

devServer: {
  historyApiFallback: true,
  static: [
    // 默认挂载工作目录下的 VOSviewer 导出目录；用 VOSVIEWER_DATA_DIR 环境变量可临时覆盖
    { directory: process.env.VOSVIEWER_DATA_DIR || absolute('..', 'vosviewer_out') },
  ],
},

说明：
- absolute() 是该文件里已有的工具函数（基于项目 __dirname 拼路径），按实际目录层级调整 '..' 的层数
- 若历史文件散在上级目录，可改挂上级目录（本次实机部署即挂载了 文献分析 整个父目录，vosviewer_out 作为其子目录同样可访问，两种挂法兼容）
- 改完配置必须重启 npm run dev 才生效

4) 启动与验证

npm run dev    # webpack-dev-server，端口 8600，热更新；首次编译约 15 秒

验证（⚠️ 本机 curl 访问 localhost 必须加 --noproxy "*"，否则环境代理会拦截返回 000）：

curl -s -o /dev/null -w "%{http_code}\n" --noproxy "*" http://127.0.0.1:8600                    # 期望 200
curl -s -o /dev/null -w "%{http_code}\n" --noproxy "*" "http://127.0.0.1:8600/<挂载目录内某文件>"  # 期望 200

JSON 网络文件格式（?json= 专用）

VOSviewer Online 的 JSON 是单一文件承载整张网络，比 map+network 双文件更适合分享/嵌入。

⚠️ 桌面版（exe / jar 1.6.21）读不了这种 JSON：-json 参数实测失效（含它自己 -save_json
的产物回灌，同样退出码 0、零输出）。所以分工是：
- 网页版：?json= 直接可用，无需转换
- 桌面版：先用 scripts/json_to_map_network.py 转回 map/network 文本（见本节末尾）

结构（顶层三个键，均非严格必需，但实际至少要 network）

{
  "info": { "title": "标题", "description": "<p>可含 HTML 的描述</p>" },
  "network": {
    "items": [
      { "id": 1, "label": "sustainable development", "x": -0.4667, "y": 0.0224,
        "cluster": 1, "weights": { "Documents": 51, "Links": 46 },
        "scores": { "Avg. pub. year": 2021.4 },
        "description": "可选，支持 HTML", "url": "可选" }
    ],
    "links": [ { "source_id": 1, "target_id": 2, "strength": 1 } ],
    "clusters": [ { "cluster": 1, "label": "Cluster 1 标签" } ]
  },
  "config": {
    "parameters": { "scale": 0.9, "simple_ui": true, "dark_ui": false,
                    "zoom_level": 1.2, "curved_links": true, "show_info": true },
    "color_schemes": { "cluster_colors": [ { "cluster": 1, "color": "#ee3e80" } ] },
    "terminology": { "item": "term", "items": "terms" },
    "templates": { "item_description": "..." },
    "styles": { "description_text": "..." }
  }
}

字段与校验规则（源码 src/workers/worker.js + src/utils/errors.js 实测）

补充行为：
- 数字型字符串会被自动转数字（"12" → 12），""/"null"/"nan" 转成 null
- 键名含 weight/score 的保持原样大小写，其余键名统一转小写（label、x、y、cluster 都是小写）
- config.parameters 里的键必须是应用支持的参数白名单（scale、item_size_variation、simple_ui、zoom_level 等），非法键会被丢弃
- 中文标签没问题，文件存 UTF-8（无 BOM 亦可）

从 map/network 生成 JSON

scripts/map_network_to_json.py 一条命令完成转换（自动识别有无表头、处理 weight<...>/score<...> 列、校验 ID 与权重）：

python scripts/map_network_to_json.py \
  --map vosviewer_out/openalex/openalex_keyword_map_laid.txt \
  --network vosviewer_out/openalex/openalex_keyword_network_vos.txt \
  --out vosviewer_out/openalex/openalex_keyword_network.json \
  --title "OpenAlex 关键词共现网络"
# [ok] ... nodes=156 links=799 cluster=yes size=58KB

实测（156 节点 / 799 连线 / 5 个聚类）转换后 ?json= 直接加载正常，与 map+network 方式渲染一致。
无坐标的 map 也能转，但前提是带 network（自动布局）；两者都没有则会明确报错。

JSON → map/network（给桌面版用）

桌面版 -json 失效，要让 exe/jar 画 JSON 里的网络，先反向转换：

python scripts/json_to_map_network.py --json vosviewer_out/openalex/xxx_network.json \
  --outdir vosviewer_out/openalex
# 产出 xxx_network_map.txt（id label x y cluster weight<..> score<..>）+ xxx_network_network.txt
# 之后照常：VOSviewer.exe -map "..._map.txt" -network "..._network.txt" -save_screenshot_png "...png"

实测：156 节点 / 799 连线的 JSON 转出后桌面版 exe 正常出图（截图 2.0MB，与直接读 map/network 一致）。
JSON 里没有坐标时脚本会提示需加 -run_layout。

自动加载网络文件（核心用法）

应用原生支持 URL 参数加载数据（数据端通过 HTTP fetch 拉取，所以文件必须在挂载目录里）：

• 路径以 / 开头的相对路径即可；默认不做代理改写（源码 getProxyUrl 的 proxy 为空时原样传递）
• ⚠️ ?json= 只接受 VOSviewer JSON 格式的网络文件；OpenAlex 原始响应等非 VOSviewer JSON 不能喂，走 map/network 配对
• 常用可视化参数：scale（整体缩放）、item_size_variation（节点大小差异）、simple_ui=true（精简界面，适合嵌入分享）、zoom_level
• 把带参数的完整 URL 存成书签/快捷方式，即"固定某网络的浏览入口"

一键打开脚本（Python，跨平台）

scripts/vosviewer-open.py 拼好 URL 并唤起默认浏览器，Windows / macOS / Linux 通吃，
cmd、PowerShell、Git Bash 里都能直接跑（无 .cmd/.bat，避免批处理转义与编码坑）：

# map + network 配对（相对数据目录的路径）
python scripts/vosviewer-open.py keyword_map.txt keyword_network.txt
python scripts/vosviewer-open.py vosviewer_out/xxx_map.txt vosviewer_out/xxx_network.txt

# 单个 VOSviewer JSON 网络文件
python scripts/vosviewer-open.py network.json

# 绝对路径：用 --data-dir 指明挂载目录，脚本会转成相对 URL 路径
python scripts/vosviewer-open.py "C:\data\keyword_map.txt" "C:\data\keyword_network.txt" --data-dir "C:\data"

# 只生成 URL 不打开浏览器（便于排错 / 手工传给别的工具）
python scripts/vosviewer-open.py --print-only keyword_map.txt keyword_network.txt

行为要点：
- 一个参数 = JSON 模式（?json=），两个参数 = map+network 模式（?map=&network=）
- \ 自动转 /，文件名做 URL 编码（中文、空格安全）
- 默认数据目录 = 当前工作目录；文件落在挂载目录之外时会打印警告（静态服务通常访问不到）
- 可选参数：--base 改服务地址（默认 http://localhost:8600）、--data-dir、--print-only

排错清单（实测汇总）

Resources

• scripts/vosviewer-open.py — 一键在浏览器中打开网络文件（拼 ?map=&network= / ?json= URL），跨平台，纯标准库，用法见上文与 --help。
• scripts/map_network_to_json.py — 把 VOSviewer map(+network) 文本文件转成单文件 JSON 网络（?json= 专用），自动识别表头、转换 weight<...>/score<...> 列、校验 ID 唯一性与权重非负。
• scripts/json_to_map_network.py — 反向转换：JSON → map + network 文本，供桌面版 exe/jar 可视化（桌面版 -json 参数实测失效，只能这样绕）。
• 跨技能依赖：~\.workbuddy\skills\vosviewer-cli\ — VOSviewer 桌面版命令行技能，数据生产端（OpenAlex 取数、建图、批量截图）；其输出目录约定（<工作目录>\vosviewer_out\）即本技能的默认挂载目录。
• 源码参考：src/utils/helpers.js（parseQueryString / getProxyUrl，URL 参数白名单）、src/store/ui/index.js（MAP / NETWORK / JSON 参数键）。