70 lines
3.3 KiB
Markdown
70 lines
3.3 KiB
Markdown
# Spine粒子连接器
|
||
|
||
该连接器让部署在服务器上的 Spine粒子编辑器网页调用用户电脑中已安装、已激活的 Spine，把网页生成的 JSON 和图片转换成 `.spine` 工程。
|
||
|
||
## 使用方法
|
||
|
||
1. 正常安装、激活 Spine。
|
||
2. 使用 `release/connector/` 中的独立版时，macOS 双击 `启动Spine连接器.command`；Windows 双击 `启动Spine连接器.bat`。独立版已内置运行环境，不需要安装 Node.js。
|
||
3. 打开 Spine粒子编辑器网页。导出区域显示“连接器可用 · Spine 已就绪”后，点击“导出 .spine 包”。
|
||
4. 服务器网站首次连接时，状态栏会显示“授权当前网站”。点击后会打开本机确认页，核对显示的完整网站来源（协议、域名和端口）后点击“允许此网站”。授权一次后，连接器会在本机保存允许列表；回到网页后最多等待 3 秒或点击“刷新”。
|
||
|
||
本地开发地址 `127.0.0.1:5173` 和 `localhost:5173` 默认允许，不需要授权。
|
||
|
||
授权按完整来源区分：`https://editor.example.com`、`http://editor.example.com` 与 `https://editor.example.com:8443` 是三个不同的授权项。生产环境建议始终使用 HTTPS 与固定域名。
|
||
|
||
网页下载的是 ZIP 压缩包，内部包含 `.spine` 工程和 JSON 引用的图片目录。浏览器不能直接下载文件夹，因此使用 ZIP 保留完整目录结构；默认结构为：
|
||
|
||
```text
|
||
SpineParticle.zip
|
||
├── SpineParticle.spine
|
||
└── images/
|
||
└── star.png
|
||
```
|
||
|
||
## 自动版本选择
|
||
|
||
连接器读取网页请求及 JSON 内的版本，两者必须一致。支持 `3.8`、`4.0`、`4.1`、`4.2`、`4.3`，调用 Spine 时分别使用 `3.8.xx` 到 `4.3.xx` 的最新可用补丁版本。
|
||
|
||
可通过环境变量覆盖自动找到的 Spine 路径：
|
||
|
||
```text
|
||
SPINE_EXECUTABLE=/自定义路径/Spine
|
||
```
|
||
|
||
也可以通过逗号分隔的环境变量预先允许生产网站：
|
||
|
||
```text
|
||
SPINE_CONNECTOR_ORIGINS=https://particle.example.com,https://editor.example.com
|
||
```
|
||
|
||
## 安全边界
|
||
|
||
- 服务只监听 `127.0.0.1:27843`，不会暴露到局域网或公网。
|
||
- 生产网站必须由用户在本机授权，授权结果保存在浏览器之外的连接器配置中。
|
||
- 接口只接受 JSON、图片、项目名称和受支持的 Spine 版本，不能执行网页提供的任意命令。
|
||
- 文件在系统临时目录转换，返回 `.spine` 后立即清理。
|
||
- 单个 JSON 最大 64MB，单图最大 32MB，图片总计最大 128MB，请求最大 200MB。
|
||
|
||
## 手动启动
|
||
|
||
在项目目录运行：
|
||
|
||
```text
|
||
npm run connector
|
||
```
|
||
|
||
健康检查地址：`http://127.0.0.1:27843/v1/health`。
|
||
|
||
## 生成不依赖 Node.js 的独立版
|
||
|
||
在目标操作系统上从项目根目录执行：
|
||
|
||
```text
|
||
npm run build:connector
|
||
```
|
||
|
||
会生成 `release/connector/<系统-架构>/` 以及同目录下的 ZIP 分发包。把整个文件夹或 ZIP 交给用户即可，里面包含独立可执行文件和不依赖 Node.js 的启停脚本。构建必须在对应系统上完成：例如 Apple Silicon、Intel Mac、Windows 分别构建各自的版本；Node SEA 不支持把当前 Mac 可执行文件直接交叉打成 Windows `.exe`。
|
||
|
||
构建后的 macOS 程序会进行临时本机签名。若要对外正式发布，仍建议使用 Apple Developer ID 重新签名并公证。
|