02 环境准备与版本选择

先选 Rhino 版本

Compute 源码分支必须与安装的 Rhino 主版本匹配：

已安装 Rhino	建议源码分支
Rhino 8	`8.x`
Rhino 7	`7.x`

如果 Rhino 版本和 Compute 分支不匹配，常见结果是编译失败、启动时找不到 Rhino 组件、Grasshopper 插件加载异常，或者运行时返回 500。

Windows 本地开发环境

本地开发和调试建议使用 Windows 工作站：

Windows 10/11 或兼容的 Windows 开发机。
Visual Studio 2022，用于打开解决方案、编译、断点调试。
Git，用于拉取 mcneel/compute.rhino3d。
Rhino 7 或 Rhino 8，并已启动过一次以完成授权。
可选：Python、Node.js、.NET SDK，用于测试客户端调用。

官方本地调试指南把本地开发定位为 Windows-only。虽然 2026 年的 Compute 指南目录已经出现 Linux Server 内容，但 Linux 版目前仍被标注为 WIP，不应把它当成稳定生产主线。

获取源码

git clone https://github.com/mcneel/compute.rhino3d.git
cd compute.rhino3d
git checkout 8.x

如果你使用 Rhino 7：

git checkout 7.x

当前工作区已有两个相关目录：

E:\tmp\compute.rhino3d
E:\tmp\compute.rhino3d-7.x

教学时可以把它们作为 Rhino 8 和 Rhino 7 分支对照材料。

解决方案结构

源码中最需要关注的目录：

路径	说明
`src\rhino.compute`	对外服务入口，管理子进程、认证、反向代理。
`src\compute.geometry`	真正加载 Rhino.Inside 并执行几何、Grasshopper、自定义端点。
`src\hops`	Grasshopper Hops 组件项目。
`src\ghhops-server-py`	Python Hops server 示例和库。
`script\production`	Windows/IIS 生产部署脚本。

环境变量速查

环境变量	作用	常见默认值或说明
`RHINO_COMPUTE_KEY`	API Key。配置后 POST 请求必须带 `RhinoComputeKey` header。	空值表示不启用认证，生产环境不建议为空。
`RHINO_TOKEN`	Core-Hour Billing token。服务器计费授权使用。	生产服务器需要。
`RHINO_COMPUTE_TIMEOUT`	服务端请求超时秒数。	常见默认值 100 秒。
`RHINO_COMPUTE_MAX_REQUEST_SIZE`	最大请求体大小，单位 byte。	常见默认 52428800，约 50 MB。
`RHINO_COMPUTE_LOG_PATH`	日志目录。	本地和部署环境可不同。
`RHINO_COMPUTE_LOG_RETAIN_DAYS`	日志保留天数。	常见默认 10。
`RHINO_COMPUTE_DEBUG`	是否开启详细日志。	调试时设为 `true`。
`RHINO_COMPUTE_LOAD_GRASSHOPPER`	启动时是否加载 Grasshopper。	默认 true；纯几何端点可设 false 加快启动。
`RHINO_COMPUTE_BLOCK_PRIVATE_URLS`	阻止服务端抓取私有、回环、链路本地地址。	对公网部署建议 true。

Windows 设置机器级环境变量示例：

[System.Environment]::SetEnvironmentVariable('RHINO_COMPUTE_KEY', 'change-me-to-a-secret', 'Machine')
[System.Environment]::SetEnvironmentVariable('RHINO_COMPUTE_DEBUG', 'true', 'Machine')

设置后需要重启相关进程。IIS 部署时通常还需要回收应用池或重启 IIS。

客户端依赖

Python：

pip install rhino3dm compute-rhino3d

JavaScript / Node.js：

npm install rhino3dm compute-rhino3d

.NET：

安装 Rhino3dm NuGet 包。
安装 Newtonsoft.Json NuGet 包。
引入官方 RhinoCompute.cs 客户端源文件或使用项目中已有封装。

版本兼容原则

Rhino 主版本、Compute 分支、Grasshopper 插件版本应保持一致。
客户端库版本应与服务端能力接近，尤其是调用新 API 或 Rhino 8 特性时。
服务器端安装第三方 Grasshopper 插件时，要保证插件版本、依赖、授权和加载路径都能在无界面环境中工作。
不要在生产服务器上随意自动更新 Rhino 或插件，先在同版本测试环境验证。

本章检查点

你是否已经确认 Rhino 主版本和 Compute 分支一致？
你是否知道 API Key 是 RHINO_COMPUTE_KEY，客户端 header 是 RhinoComputeKey？
你是否能解释哪些环境变量影响超时、请求体大小和日志？

目录