Revit链接文件未在Autodesk Forge Viewer显示问题排查

• 压缩包内路径结构与Revit本地路径不匹配
  Revit的相对路径是基于根文件的本地目录结构定义的，压缩包必须完全复刻这一结构。比如本地根文件在项目根目录/Main.rvt，链接文件在项目根目录/Links/Sub.rvt，那压缩包里必须保持Main.rvt和Links/Sub.rvt的层级，不能把所有文件平放在压缩包根目录，也不能嵌套多余文件夹。
  排查：解压压缩包，对比本地Revit项目的目录结构，确保完全一致。

• rootFilename参数指定错误
  该参数必须精确匹配压缩包内根Revit文件的完整文件名（含扩展名），大小写也要完全一致（比如根文件是MainModel.rvt，不能写成mainmodel.rvt或MainModel）。
  排查：核对转换任务配置中rootFilename的值与压缩包内根文件名，逐字符确认。

• 压缩包格式或压缩方式不兼容
  Model Derivative API仅支持标准ZIP格式，不支持RAR、7Z等格式；同时不能使用加密压缩，压缩时必须保留原目录结构（部分压缩工具会自动扁平化文件路径，导致链接路径失效）。
  排查：用系统自带压缩工具（如Windows“发送到压缩(zipped)文件夹”）重新打包，确保路径和文件名无误。

• 链接文件存在损坏或版本兼容问题
  如果链接的Revit文件在本地打开就有加载错误，或者版本高于根文件（Revit不支持高版本链接低版本主文件），转换时会自动忽略链接文件。
  排查：在本地Revit中打开根文件，确认所有链接正常加载无警告；检查根文件与链接文件的Revit版本，确保主文件版本≥链接文件版本。

• 转换任务输出配置不完整
  即使目标是SVF2，也要确保output节点正确指定type为svf2，且views参数包含所需视图类型（比如只指定2d但链接文件只有3D内容）。
  排查：确认转换配置类似以下结构：

  {
    "input": {
      "urn": "压缩包的URN",
      "compressedUrn": true,
      "rootFilename": "根文件名.rvt"
    },
    "output": {
      "formats": [
        {
          "type": "svf2",
          "views": ["2d", "3d"]
        }
      ]
    }
  }
  

• URN或权限问题
  若压缩包的URN获取无效，或转换用的访问令牌缺少data:read/data:write权限，API无法正确读取压缩包内的链接文件。
  排查：确认压缩包的URN有效；检查访问令牌的权限范围是否包含所需权限。

内容的提问来源于stack exchange，提问作者MASAMIKI