简介：Autodesk Forge是面向云端应用开发的平台，这套资源包即为C#开发者提供的完整入门资料。内容围绕数据管理、模型衍生、设计自动化、在线查看器四大核心服务，说明了如何通过OAuth完成安全认证，如何上传并转换设计文件，如何调用自动化任务，以及如何嵌入三维模型预览。同时涵盖BIM 360项目协作和常见错误处理、性能优化等实践要点。压缩包共104个文件，以xml配置、dll库、cs源码、txt说明为主，另有解决方案文件、工程文件、NuGet包和缓存调试文件，整体约1.29MB，目录结构清晰，便于按模块对照学习。资源已有349人学习下载，适合刚开始接触Forge .NET开发套件，或希望将模型转换、设计自动化功能接入到已有C#项目中的开发者。利用包内的示例代码与工程骨架，可以直观理解各类API的调用顺序、参数配置和返回处理，快速搭建可运行原型，降低官方文档的阅读门槛，缩短功能验证周期。
1. Autodesk-Forge 到底是什么、解决谁的痛
做建筑设计或制造信息化的人，大概率都遇到过这种局面：图纸在 Revit、AutoCAD 里躺着，客户却问能不能在手机上看；审图要装一整套设计软件，版本不对还打不开；模型改了几版，导出的文件散落在网盘里，连个统一视图都没有。Autodesk-Forge 这套云平台 API 就是为这些场景准备的：它把桌面软件里最重的那套能力——读取模型、解析几何、渲染图纸——拆成一个个 Web 服务，供你按需调用。你不需要自己的服务器装 Revit，不需要研究 DWG 二进制格式，更不用从头写一个 WebGL 渲染引擎，只要拿到凭证、调用接口、集成一个 Viewer，就能在浏览器里打开、旋转、剖切、查属性。它适合两类人：一类是想把图纸/模型能力放进自研系统的开发者，另一类是正在做 BIM 协同或设计交付平台的创业团队。这篇不走概念，直接讲清它怎么用、有哪些参数、真实项目里坑在哪。
2. 先搞懂 Forge 的三类服务和认证机制
2.1 核心服务划分：Data Management、Model Derivative 与 Viewer
Forge 平台虽然名义上有很多 API，但落地项目里你真正高频用到的，基本就三类：Data Management 负责文件存储和版本管理，Model Derivative 负责把原始文件转换成可在网页端展示的格式并提取属性，Viewer 是前端渲染组件。先想明白这三者在一次完整调用里的顺序，后续才能不绕路。
如果把一次在线看模型的流程画出来，Data Management 扮演的是“门口柜子”的角色。你先建一个 Bucket（存储桶），拿到一个 Object Key，把 DWG 或 RVT 文件上传上去。这时候文件只是被托管了，网页端还不能直接读它。Model Derivative 接的才是“翻译”这一棒，它读取这个文件，输出一种叫 SVF / SVF2 的增量渲染格式。Viewer 要的恰恰就是这种格式，它通过一个 Token 和 URN 去取渲染数据，在浏览器里绘制出能转、能缩放、能点选的三维模型。
这三块在官方文档里其实是三组独立的 API，但从一个完整业务链看，它们必须串起来用。我见过不少人只盯住 Viewer，以为集成一个 JS 库就能打开模型，结果卡在上传和转换环节上。记住：Viewer 永远不是第一个被调用的服务，它依赖前面的转换产物。项目初期就把数据流理顺，后面加需求（比如在线校对、版本回溯）会顺畅很多。
// 一次完整数据流的示意 上传 → Bucket 存储 → 触发转换 → 得到 URN → Viewer 按 URN 渲染2.2 三种 OAuth 凭据：什么时候用哪一种
Forge 的认证走的是 OAuth 2.0，官方提供三种凭据类型：Client Credentials 用于服务端对服务端的短期令牌，Authorization Code 用于让终端用户授权你的应用读取他在 Autodesk 云里的数据，Authorization Code + PKCE 则是浏览器端纯前端应用常用的一种，无需管理客户端密钥。绝大多数业务里，前面那种最常用。
Client Credentials 拿 Token 的套路非常简单：把 Client ID 和 Client Secret 拼成 Base64，再带上grant_type=client_credentials和固定的scope=viewables:read去 POST 一个 Token 端点，返回的access_token默认有效期一小时。注意 scope 不是越多越好，比如你只是查看模型，那viewables:read就足够，不需要申请data:write。给内部系统和外部客户做对接时，Token 权限控制得越细，出安全事故的概率越低。
如果你做的是 To B 交付，需要帮客户读取他自己账号下的文件，那就得让客户走一次 Authorization Code 流程，拿到属于他账号的项目数据。这个流程需要回调地址，需要维护 refresh_token，体验上比 Client Credentials 重得多。我的建议是：能用服务端令牌的就别引入用户授权，先跑通业务再谈账号体系打通。
2.3 创建一个应用的最小步骤：从注册到拿到第一对凭据
这一步不复杂，但很多人会卡在官网后台里找不到地方。到了 Forge 开发者门户后，登录进 Account 区域，进入 My Apps，新建应用，填应用名称和回调 URL，创建后页面会显示 Client ID 和 Client Secret。这个 Secret 只显示一次，务必自己保存好，不然就得重置。
拿到凭据后，先用现成工具验证一下能不能请求通。常见做法是放到 Postman 里，也可以写个几十行的脚本直接打。下面是一次最简单的 Python 脚本请求，作用是换取一个带有viewables:read权限的访问令牌。
import base64 import requests client_id = "你的 Client ID" client_secret = "你的 Client Secret" # 将凭证编码，Forge 要求 Basic Auth auth_str = base64.b64encode( f"{client_id}:{client_secret}".encode("utf-8") ).decode("utf-8") headers = { "Authorization": f"Basic {auth_str}", "Content-Type": "application/x-www-form-urlencoded" } data = { "grant_type": "client_credentials", "scope": "viewables:read" } response = requests.post( "https://developer.api.autodesk.com/authentication/v2/token", headers=headers, data=data ) print(response.status_code) print(response.json().get("access_token", "请求失败，检查返回信息"))这段脚本注意两点。第一，scope顺序官方要求固定为viewables:read，不要写成read:viewables，否则会有范围校验问题。第二，如果返回 401，先检查client_id和client_secret是否复制完整，最常翻车在 Secret 末尾多复制了一个空格，Base64 编码变了，整个请求就废了。Token 获取成功后就缓存起来，不要每个请求都重新换一遍，服务端限流在项目并发上来后会教你怎么做人。
3. 把模型送进 Forge：上传、转换、取 URN 三步齐活
3.1 创建 Bucket 并上传文件：存储策略里的几个约束
Data Management API 里，创建 Bucket 时有个参数叫policyKey，可选值就三种：transient（10 天有效期）、temporary（30 天）、persistent（永久）。这个参数直接影响你的存储成本和交付方式。
如果你的场景就是给客户临时看个模型，选transient就够了，到期自动清理，不用自己写删文件逻辑。如果是自建图纸管理平台，那就得用persistent。但注意，persistent会持续产生存储费用，而且 Bucket 的 Key 在同一账号下全局唯一，创建过一次就不能再建，若报“Bucket 已存在”的错，合理处理方式是捕获异常后直接复用旧 Bucket。常见做法是把 Bucket Key 按团队或项目命名，例如dm_bucket_proj_a_001，方便后续维护。
上传文件这一步用的是objects接口，请求路径里会带上 Bucket Key 和 Object Key。Object Key 可以带斜杠模拟目录层级，Forge 不会真建目录，它只是把斜杠当成名字的一部分，不影响功能。上传时如果文件超过几百 MB，建议走分片上传（Upload with resumable），不仅断点续传，而且对超时的容忍度高很多。
# 上传文件到 Forge，假设已经拿到 token curl --request PUT \ --url "https://developer.api.autodesk.com/oss/v2/buckets/{bucketKey}/objects/{objectKey}" \ --header "Authorization: Bearer {ACCESS_TOKEN}" \ --header "Content-Type: application/octet-stream" \ --data-binary "@model.rvt"注意这里没有走分片，只是一个最简示意。生产环境里，超过 100MB 的 RVT 文件我一般直接用官方 SDK 里的分片上传方法，可以省去自己拼请求的麻烦。上传完成后返回的objectId后面要用，但这个值不是最终给 Viewer 的 URN，还需要经过一步转换。
3.2 触发 Model Derivative 转换任务：参数和等待策略
文件落库以后，调用 Model Derivative 的接口发起转换。请求体里要指定输入文件的 URN、根文件名，以及输出的格式类型。注意 URN 是上传完成后拿objectId做一次 Base64 编码再 URL 转义得到的，不是原样传objectId。
第一次跑通这个流程的人，十个有八个会在这里怀疑自己拿错了 ID，因为转换接口返回的是一个 Job 任务标识，不是直接给你一个可访问的模型 URL。正确姿势是先提交转换任务，再拿 Job ID 去轮询转换状态，状态变成success后，才能根据需要提取模型的 Viewable 信息。
import requests import base64 # objectId 来自上传接口的返回 object_id = "urn:adsk.objects:os.object:your-bucket/your-file.rvt" urn = base64.b64encode(object_id.encode("utf-8")).decode("utf-8") # URN 传到 URL 里需要做一次 quote from urllib.parse import quote url_urn = quote(urn, safe="") payload = { "input": {"urn": url_urn}, "output": { "formats": [ { "type": "svf2", "views": ["2d", "3d"] } ] } } headers = { "Authorization": "Bearer {ACCESS_TOKEN}", "Content-Type": "application/json" } response = requests.post( "https://developer.api.autodesk.com/modelderivative/v2/designdata/job", headers=headers, json=payload ) print(response.json()) # 返回里会带一个 urn 属性，那是新的可转换状态查询用的这里头的type字段，svf是老格式，svf2是新格式，加载速度和渲染质量都有优势，新项目不要犹豫，直接用svf2。如果原始文件里有 2D 图纸，views里加上"2d"，否则提取不到平面视图。输入格式也不仅仅限于 RVT，DWG、IFC、OBJ 甚至 Navisworks 文件都能转，选型时以官方支持列表为准。
转换是异步任务，一个几百 MB 的文件快则一两分钟，慢则小十分钟，取决于模型复杂度和服务端负载。轮询接口返回的状态判断是否完成，别用固定 sleep 死等，处理异常时要考虑任务失败的可能。
3.3 拿到 Viewable 列表：给 Viewer 一个可加载的起点
转换完成之后，很多人以为拿 URN 直接喂给 Viewer 就行，实则还要再问一次模型衍生接口要 Viewable 列表。一个 RVT 文件转出来往往包含多个 Viewable，例如某个三维视图加若干 2D 立面，前端需要先请求这些清单，再决定默认先加载哪个。
# 获取模型视图清单 response = requests.get( "https://developer.api.autodesk.com/modelderivative/v2/designdata/{urn}/metadata" .replace("{urn}", quote(urn, safe="")), headers={"Authorization": "Bearer {ACCESS_TOKEN}"} ) print(response.json()) # data[].objects[] 里会有多个 viewable，取其中 name 含 "3D" 的作为默认视图返回结果里每个 Viewable 都带一个guid，Viewer 加载模型时要传这个值。不传会怎样？它会默认加载第一个 Viewable，很多 RVT 文件第一个可能是场地平面，结果前端用户一打开看到的是顶视图，还以为模型出 bug 了。把这一步做在前端初始化流程之前，能避免一半以上的“模型加载不出来”反馈。
4. 集成 Viewer：初始化参数、扩展机制与常见交互改造
4.1 一个可用的 Viewer 初始化模板
Viewer 是纯前端库，官方提供了 npm 包和 CDN 两种加载方案。国内项目普遍用 npm 方式配合打包工具，这样版本可控、按需引入。初始化的核心就三步：引入样式和脚本，创建容器 DOM，用Autodesk.Viewing.Initializer初始化，然后调用start加载指定 URN。
下面这段是把 RVT 模型加载进页面的最小实现，前提是你已经拿到了上一步的 URN 和 Viewable 的 GUID。
import { initialize } from 'forge-viewer'; const config = { env: 'AutodeskProduction', api: 'denaliV2', getAccessToken: (onTokenReady) => { // 这里从会话里取出后端换的 token const token = sessionStorage.getItem('forge_token'); const expire = sessionStorage.getItem('forge_token_expire'); onTokenReady(token, parseInt(expire) - 60); } }; const viewerDiv = document.getElementById('forgeViewer'); Autodesk.Viewing.Initializer(config, () => { const viewer = new Autodesk.Viewing.GuiViewer3D(viewerDiv, {}); viewer.start(); viewer.loadDocumentNode( 'urn:你的模型URN', 'viewableGuid', { placement: { globalOffset: { x: 0, y: 0, z: 0 } } } ); });getAccessToken这个回调每次过期都会自动触发，所以过期时间一定要比实际值短一些，留几十秒余量，否则会出现模型加载到一半 Token 失效的现象。loadDocumentNode的第二个参数就是刚才提的 Viewable GUID。placement.globalOffset在模型坐标很大时非常关键，默认值容易导致渲染后模型被“裁剪”，不过大部分项目可以先不管它。
4.2 用 Extension 扩展 Viewer：别在原生事件里堆逻辑
Forge Viewer 提供了扩展机制，逻辑上类似插件系统。功能一多，你要是直接把监听事件全写在初始化回调里，代码很快会膨胀成一座不可维护的屎山。正确做法是把一类功能封装成一个 Extension，注册后在 viewer 上加载和卸载。
一个最简单的扩展，作用是点击模型构件时弹出它的属性表。这里要说明的是，Forge 允许加载模型后动态查询属性，官方也有自带属性面板，但样式和交互跟自研系统往往不一致，很多团队都会自己重写一个。
class PropertyPanelExtension extends Autodesk.Viewing.Extension { constructor(viewer, options) { super(viewer, options); this.onSelection = this.onSelection.bind(this); } load() { this.viewer.addEventListener( Autodesk.Viewing.SELECTION_CHANGED_EVENT, this.onSelection ); return true; } unload() { this.viewer.removeEventListener( Autodesk.Viewing.SELECTION_CHANGED_EVENT, this.onSelection ); return true; } onSelection(e) { if (!e.model || e.dbIdArray.length === 0) return; const dbId = e.dbIdArray[0]; this.viewer.getProperties( dbId, props => console.log('构件属性', props) ); } } viewer.registerExtension('PropertyPanelExtension', PropertyPanelExtension); // 使用时 viewer.loadExtension('PropertyPanelExtension');选择事件里的dbIdArray是选中构件在模型内部的数据库 ID。注意一点，不同模型文件的同一根构件的 dbId 没有可比性，它们是模型转换时重新生成的。如果有业务上需要把构件 ID 和外部系统的编码对应起来，通常做法是在 RVT 里写共享参数，转换后通过属性面板去读这个值。
4.3 剖切、聚焦、隔离三个高频能力怎么调
做设计交付平台时，剖切是刚需。Viewer 内置了剖切工具，但默认 UI 不够明显，需要自己添加一个按钮或用脚本触发。实现上，加载Autodesk.Section扩展，然后调用工具开启剖切面，之后用户就能在模型上拖动剖切面。
聚焦功能看似简单，但很多人找不到入口。viewer.fitToView(true)能把视角切回合适位置，但如果只需要聚焦到某个构件，正确方式是先选中它，再调用viewer.fitToView([dbId])。隔离功能同理，通过viewer.isolate(dbIdArray)只展示选中的构件，其余全部隐藏。这三个操作是审图场景使用频率最高的交互，建议直接封装成自定义工具栏按钮，不要强行让用户研究官方那个默认工具条的层级。
// 聚焦到指定构件 function focusOnDbIds(dbIds) { viewer.select(dbIds); // 选中 viewer.fitToView(dbIds); // 调整视角 viewer.isolate(dbIds); // 隔离显示 }注意fitToView接受数组参数时，会把所有选定构件的包围盒纳入视野，这对多个构件对比非常有用。调用顺序先select再fitToView，否则视角调整了但选中状态可能不符合预期，因为 select 会触发渲染更新，fitToView 内部的包围盒计算需要拿到最新的选中状态。
5. Forge 实践中的五个高频坑与排查思路
5.1 模型转换任务一直卡在 processing
现象：提交转换任务后，轮询状态长时间停留在processing，甚至超过半小时没变化。 原因：文件太大且几何复杂，服务端排队时间长；更常见的是文件本身有问题，比如 RVT 缺少材质贴图或链接文件缺失，转换器在等待未知资源直到超时。 解决：先去查文件的链接模型和贴图路径。RVT 文件如果有外部链接，转之前要确保链接文件一并上传或已绑定。其次观察提交任务的 Job 返回是否带progress字段，若一直不变，多半是文件内部数据问题。逐层排查，必要时将 RVT 转为本地 IFC 再上传，绕开对链接文件的依赖。
5.2 前端加载模型报 403 Forbidden
现象：Viewer 初始化正常，但loadDocumentNode或者在viewer.start后请求资源时出现 403。 原因：最常见的是 Token 过期，但还有一种隐蔽情况，是后端换取的 Token scope 只有viewables:read，但请求关联了 Data Management 的文件元数据接口，权限范围不够。 解决：先看 403 出现在哪个 URL 上。如果是模型数据相关 URL，刷新 Token 重试；如果是md/derivative/v2/...路径，检查 Token 的 scope 是否包含data:read。不建议一上来就给 Token 加全部 scope，按业务链路“缺什么补什么”最稳妥。
5.3 SVF2 格式的模型加载白屏或半透明
现象：代码完全按照文档写，转换也显示成功，但 View 里模型是白屏或部分构件透明。 原因：SVF2 对浏览器 WebGL 版本有要求，部分低版本浏览器或者某些国产浏览器的 WebGL 实现有问题，加载不完整；另外模型里如果有大量 PBR 材质，对应着色器在部分显卡上没法正常渲染。 解决：先换一个官方示例模型测试 Viewer 环境，若示例正常，那就是模型材质兼容性问题，尝试在转换时选择svf老格式做对比；若示例也白屏，优先在 Chrome 里检查 WebGL 状态，更新显卡驱动。这个坑偶尔出现，但一出现就很迷惑，建议把浏览器版本和 WebGL 支持写进在线预览页的启动检测。
5.4 Bucket Key 已存在的错误
现象：创建 Bucket 时接口返回Bucket already exists，但你自己明明记得没建过。 原因：Bucket Key 在 Forge 账号级别是所有应用共享的，也许同组同事在其他应用里已用过这个名字。 解决：建 Bucket 的 Key 时加一个项目前缀或随机串，避免冲突。代码里捕获这个异常，返回现有 Bucket 直接使用。更省心的是在上传 SDK 封装里做一个“查一下存在就复用”的函数，幂等处理。
5.5 权限模型和过期策略导致的“换个人就加载失败”
现象：A 开发的系统，B 拿去部署后模型加载不出来，后端日志一切正常。 原因：Forge 应用有开发环境和生产环境之分，B 部署时如果创建了另一个应用，拿到的 Client ID 不同，而前端 Token 是后端从某个固定应用获取的，一旦复制的环境变量没替换全，就会出现鉴权失败。 解决：部署前检查环境变量是否完整，确认生产端 Forge 应用的凭据被正确替换。特别是有的项目里 Token 获取逻辑写在网关层，导出镜像时容易遗漏替换，这一步时常要加入上线 checklist。
6. 把 Forge 嵌入真实业务的三个可选技巧
6.1 用 Forge 做一套内部审图工具的关键链路选择
很多团队最初只是要“让客户能看图”，但落到真实业务里，往往变成“在网页里做批注、按楼层查看、对构件问题做定位”。这个时候，单纯靠 Viewer 基础功能是不够的，要设计自己的数据切片。常见做法是把图形与业务数据分离——Viewer 负责图形，批注和任务信息存你自己的数据库，二者用 dbId 或自定义属性编码关联。好处是图形从 Forge 拉取，业务数据在你手里，离线审批、权限控制都可以自行决定。
我经历过的某个模拟项目X，最初就是让现场人员用平板在模型上标记问题，后来要求加上“按责任单位过滤构件高亮”。如果当时真按默认思路把构件信息全部交给前端在浏览器里过滤，几千个构件切换时一定会卡。后来改成在后端用属性值筛选，返回 dbId 集合给前端高亮，流畅度立刻就上来了。
6.2 转换中直接生成 PDF 图纸，避免前端画图踩坑
有个经常被忽略的能力：Model Derivative 不仅出 SVF，还能直接产出 PDF。当你需要在网页上保留规范图框的布局、异形房间的轴号等细节时，前端完全重绘通常是不现实的。正确打开方式是在转换任务里指定一个额外的 output 格式，让服务端生成一份 PDF 文件，前端用链接直接打开或下载。
这样做还有个好处，图纸文件可以一次性生成全册，打印时不用前端重新排版。不过要注意，从 RVT 转换出来的 PDF 一般对图框、标注的还原度很好，如果是 CAD 底图混排的情况，可能个别字体和线型会有变化，出正式交付文档前需要人工核对一版。
# 转换任务增加 PDF 输出 payload = { "input": {"urn": url_urn}, "output": { "formats": [ {"type": "svf2", "views": ["2d", "3d"]}, {"type": "pdf", "views": ["2d"]} ] } }pdf类型不需要额外参数，views填["2d"]表示只导出二维视图。转换完成后，模型衍生接口的结果列表里会多出一个 PDF 下载地址。很多团队把这个地址存在自己的文件服务里做一层跳转，一方面能控制访问权限，另一方面可以绕开 Forge 链接的过期时间。
6.3 初始化时设置合适的全局偏移与单位
如果你处理的 BIM 模型源于某园区或市政项目，原始坐标系动辄上百万米，Viewer 默认的浮点精度会在渲染时抖动。这个现象在行业里叫“远处坐标抖动”，直观表现是模型在旋转时轻微颤动，或构件边缘发虚。
解决参数就是前面提过的globalOffset。常见做法是取模型第一个 Viewable 的 bounding box 中心点作为偏移量，在加载所有模型时复用同一个偏移值，避免多模型合模时出现错位。同时检查设计文件的单位设置，有些 RVT 文件的单位是英尺，前端如果是按毫米在算盒子大小，测量工具的数值会全部对不上。
const viewer = new Autodesk.Viewing.GuiViewer3D(container, { globalOffset: { x: 123456.78, y: 234567.89, z: 0 } });这套方案在模拟项目X里救过一次现场：当时某设备模型在浏览器里只要一转就抖，加了中心点偏移后彻底恢复稳定。记住两个原则：偏移量在项目内全局统一，单位转换在数据入库时就定好。
做 Forge 集成这两年，最深的体会是它对外号称“低代码”的部分其实都暗含前置条件，泰半的翻车都出在认证、URN 编码和格式选型这些琐碎环节。把这些前置条件整理成团队内部手册，让新成员照着走一遍，省下来的扯皮时间足够把 Viewer 的交互打磨到贴合业务，而不是天天在 API 文档里打转。希望这篇能帮你少踩几个坑。
本文还有配套的精品资源，点击获取
