Power BI Desktop 项目报表文件夹

本文介绍 Microsoft Power BI Desktop 项目的“报表”文件夹中的文件和子文件夹。这里的文件和子文件夹代表 Power BI 报表。根据项目不同，报表文件夹可以包括：

.pbi\
- localSettings.json
CustomVisuals\
StaticResources\
- RegisteredResources\
semanticModelDiagramLayout.json
definition.pbir¹
mobileState.json
report.json²
定义\ 文件夹³
平台

1 - 此文件是必需的。
2 - PBIR-Legacy 格式需要此文件。
3 - 此文件是 PBIR 格式所必需的。

并非每个项目报表文件夹都包含文中介绍的所有文件和子文件夹。

报告文件

.pbi\localSettings.json

包含仅适用于当前用户和本地计算机的报表设置。应将其添加到 .gitignore 或其他源代码管理排除列表中。默认情况下，Git 会忽略此文件。

有关详细信息，请参阅 localSettings.json 架构文档。

CustomVisuals\

该子文件夹包含报表中的自定义视觉对象的元数据。 Power BI 支持三种类型的自定义视觉对象：

组织商店中的视觉对象 - 组织可以批准自定义视觉对象，并将其部署到其组织的 Power BI 中。若要了解详细信息，请参阅组织存储。
AppSource Power BI 视觉对象 - 也称为“公共自定义视觉对象”。这些视觉对象可从 Microsoft AppSource 中获取。报表开发人员可以直接从 Power BI Desktop 安装这些视觉对象。
自定义视觉对象文件 - 也称为“专用自定义视觉对象”。可以通过上传 pbiviz 包将文件加载到报表中。

只有专用自定义视觉对象才会加载到 CustomVisuals 文件夹中。 AppSource 和组织视觉对象将通过 Power BI Desktop 自动加载。

RegisteredResources\

该子文件夹包含特定于报表并由用户加载的资源文件，例如自定义主题、图像和自定义视觉对象（pbiviz 文件）。

开发人员负责管理此处的文件，并且支持更改。例如，你可以更改文件，当 Power BI Desktop 重启后，新文件将加载到报表中。此文件夹可以取消阻止一些有用的方案，例如：

使用公共架构在 Power BI Desktop 外部创作自定义主题。
通过更改多个报表上的资源文件来应用批量更改。例如，可以切换公司的自定义主题、在浅色和深色主题之间更改，以及更改徽标图像。

每个资源文件都必须在 report.json 文件中具有相应的条目。仅支持对 RegisteredResources 文件进行编辑，前提是相关资源已加载，且会使 Power BI Desktop 在 report.json 中注册该资源。

semanticModelDiagramLayout.json

包含数据模型关系图，它描述了与报表关联的语义模型的结构。此文件不支持外部编辑。

definition.pbir

包含报表和核心设置的总体定义。此文件还包含对报表使用的语义模型的引用。 Power BI Desktop 可以直接打开 PBIR 文件，就像从 PBIP 文件打开报表一样。打开 PBIR 文件时，如果存在相对引用 byPath，会同时打开语义模型。

示例 definition.pbir：

{  
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/2.0.0/schema.json",
  "version": "4.0",
  "datasetReference": {
    "byPath": {
      "path": "../Sales.Dataset"
    }    
  }
}

定义包括 datasetReference 属性，该属性引用报表中使用的语义模型。引用可以是以下任一项：

byPath - 指定目标语义模型文件夹的相对路径。不支持绝对路径。使用正斜杠 (/) 作为文件夹分隔符。使用时，Power BI Desktop 还会在完全编辑模式下打开语义模型。

byConnection - 使用连接字符串指定与 Fabric 工作区中的语义模型的连接。使用 byConnection 引用时，Power BI Desktop 不会在编辑模式下打开语义模型。

第 2 版
版本 1

使用 byConnection 引用时，必须指定以下属性：

属性	说明
connectionString	用于引用 Fabric 工作区中语义模型的连接字符串。

使用 byConnection 的示例：

{  
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/2.0.0/schema.json",
  "version": "4.0",
  "datasetReference": {
    "byConnection": {      
      "connectionString": "Data Source=\"powerbi://api.powerbi.com/v1.0/myorg/[WorkpaceName]\";initial catalog=[SemanticModelName];access mode=readonly;integrated security=ClaimsToken;semanticmodelid=[SemanticModelId]"
    }
  }
}

通过 Fabric REST API 部署报表时，只需指定 semanticmodelid 属性。例如：

{  
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/2.0.0/schema.json",
  "version": "4.0",
  "datasetReference": {
    "byConnection": {      
      "connectionString": "semanticmodelid=[SemanticModelId]"
    }
  }
}

使用 byConnection 引用时，必须指定以下属性：

属性	说明
connectionString	用于引用 Fabric 工作区中语义模型的连接字符串。
pbi模型数据库名称	远程语义模型标识符。
连接类型	连接类型。对于服务远程语义模型，此值应为 `pbiServiceXmlaStyleLive`。
pbiModelVirtualServerName	应具有值 `sobe_wowvirtualserver` 的内部属性。
pbiServiceModelId	应具有值 `null` 的内部属性。
姓名	应具有值 `EntityDataSource` 的内部属性。

使用 byConnection 的示例：

{
    "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/1.0.0/schema.json",
    "version": "4.0",
    "datasetReference": {  
      "byConnection": {
        "connectionString": "Data Source=powerbi://api.powerbi.com/v1.0/myorg/[WorkpaceName];Initial Catalog=[SemanticModelName];Integrated Security=ClaimsToken",
        "pbiServiceModelId": null,
        "pbiModelVirtualServerName": "sobe_wowvirtualserver",
        "pbiModelDatabaseName": "[Semantic Model Id]",
        "connectionType": "pbiServiceXmlaStyleLive",
        "name": "EntityDataSource"
      }
  }
}

重要

通过 Fabric REST API 部署报表时，必须使用 byConnection 引用。这不应与语义模型的存储模式（如 DirectQuery）混淆。报表 datasetReference 中仅指定报表连接到的语义模型，它不定义该模型如何存储或访问其数据。

多个 *.pbir 文件

当语义模型和报表共享同一工作区时， Fabric Git Integration 始终使用 byPath 对语义模型的引用导出定义。如果要强制报表在实时连接中打开（例如，使用报表级指标），可以有多个 *.pbir 文件，例如一个具有 byPath 连接的文件，另一个具有 byConnection 连接的文件。 Fabric Git 集成仅处理 definition.pbir 文件，并忽略所有其他 *.pbir 文件。但是，这些文件可以共存在同一存储库中。

  ├── definition\
  ├── StaticResources\
  ├── .platform
  ├── definition-liveConnect.pbir
  └── definition.pbir

该文件 definition.pbir 还通过“version”属性指定支持的报表定义格式。

版本	支持的格式
1.0	报表定义必须以 PBIR-Legacy 格式存储在 report.json 文件中。
4.0 或更高版本	报表定义可以存储为 PBIR-Legacy（report.json 文件）或 PBIR（\definition 文件夹）。

有关详细信息，请参阅 definition.pbir 架构文档。

mobileState.json

包含在移动设备上呈现时的报表外观和行为设置。此文件不支持外部编辑。

report.json

此文件包含采用 Power BI 报表旧版格式 (PBIR-Legacy) 的报表定义，不支持外部编辑。

定义\ 文件夹

仅当 Power BI 项目使用 Power BI 增强型报表格式 (PBIR) 保存时，此文件夹才可用。它将替换 report.json 文件。

.platform

Fabric 平台文件，其中包含对于建立和维护 Fabric 项目与 Git 之间的连接至关重要的属性。

若要了解详细信息，请参阅 Git 集成自动生成的系统文件。

PBIR 格式

使用 Power BI 增强型报表格式 (PBIR) 保存 Power BI 项目文件 (PBIP) 可通过使用格式正确的 JSON 文件极大地改进更改跟踪和合并冲突解决。

易于阅读的 PBIR 差异截图。

每个页面、视觉对象、书签等组织到文件夹结构中的单独文件中。此格式非常适合协同开发中的冲突解决。

友好 PBIR 文件夹的屏幕截图。

与 PBIR-Legacy (report.json) 不同，PBIR 是一种公开记录的格式，支持非 Power BI 应用程序的修改。每个文件都有一个公共 JSON 架构，它不仅可以记录文件，还可以让代码编辑器（例如 Visual Studio Code）在编辑时执行语法验证。

目前可以使用 PBIR 的一些应用场景包括：

在报表之间复制页面、可视化对象和书签。
通过复制和粘贴视觉对象文件，确保所有页面的一组视觉对象的一致性。
在多个报表文件中轻松查找和替换。
使用脚本对所有视觉对象进行批量编辑（例如，隐藏视觉对象级别筛选器）

使用 PBIR 另存为项目

使用 PBIR 保存项目时，报表保存在报表文件夹内名为 \definition 的文件夹内：

报表 PBIP 文件夹中定义文件夹的屏幕截图。

详细了解 PBIR 文件夹结构。

PBIR 文件夹和文件

报表定义存储在具有以下结构的 definition\ 文件夹中：

├── bookmarks\
│   ├── [bookmarkName].bookmark.json
|   └── bookmarks.json
├── pages\
│   ├── [pageName]\
│   |   ├── \visuals
|   │   |   ├── [visualName]\
|   |   │   │   |── mobile.json
|   |   |   └   └── visual.json
|   |   └── page.json
|   └── pages.json
├── version.json
├── reportExtensions.json
└── report.json

文件/文件夹	必填	说明
书签\	否	存放该报表所有书签文件的文件夹。
• [bookmarkName].bookmark.json	否	书签元数据，例如目标视觉对象和筛选器。有关详细信息，请参阅架构。
bookmarks.json	否	书签元数据，例如书签顺序和组。有关详细信息，请参阅架构。
页面\	是	包含报表的所有页面的文件夹。
── [pageName]	是	每页一个文件夹。
视觉内容	否	包含页面的所有视觉对象的文件夹。
────── [visualName]\	否	每个可视化对象对应一个文件夹。
──────── mobile.json	否	视觉对象移动布局元数据，例如移动位置和格式设置。有关详细信息，请参阅架构。
─────── visual.json	是	视觉对象元数据，例如位置和格式、查询。有关详细信息，请参阅架构。
page.json	是	页面元数据，例如页面级别筛选器和格式设置。有关详细信息，请参阅架构。
pages.json	否	页面元数据，例如页面顺序和活动页。有关详细信息，请参阅架构。
version.json	是	PBIR 文件版本以及其他因素决定了要加载的必需文件。有关详细信息，请参阅架构
reportExtensions.json	否	报表扩展，例如报表级别度量值。有关详细信息，请参阅架构
report.json	是	报表元数据，例如报表级别筛选器和格式设置。有关详细信息，请参阅架构

重要

某些报表元数据文件（如 visual.json 或 bookmarks.json）可以使用语义模型中的数据值进行保存。例如，如果将筛选器应用于字段“Company”= “Contoso”的视觉对象，则值“Contoso”将保留为元数据的一部分。这也适用于其他配置，例如切片器选择、矩阵自定义列宽度和特定系列的格式设置。

PBIR 命名约定

上表中方括号（[]）中的所有名称都遵循默认命名约定，但可以重命名为更易用的名称。默认情况下，页面、视觉对象和书签使用其报表对象名称作为其文件或文件夹名称。这些对象名称最初是一个 20 个字符的唯一标识符，例如“90c2e07d8e84e7d5c026”。

PBIR 名称属性的屏幕截图。

支持重命名每个 JSON 文件中的“name”属性，但可能会破坏报表内外的外部引用。对象名称和/或文件/文件夹名称必须包含一个或多个单词字符（字母、数字、下划线）或连字符。

重命名任何 PBIR 文件或文件夹后，必须重启 Power BI Desktop。重启后，Power BI Desktop 将在保存时保留原始文件或文件夹名称。

复制报表对象名称

报表中的每个对象都保存在单独的文件夹或文件中，但文件夹的名称并不总是显而易见的。为方便起见，可以直接将任何报表对象名称（包括页面、视觉对象、书签和筛选器）的名称从 Power BI 复制到剪贴板。

报表的屏幕截图，其中一个视觉对象有一个箭头指向其相应文件的名称。

从桌面
从服务中

转到文件> 选项和设置> 报表设置> 报表对象，并启用右键单击报表对象时复制对象名称设置。此操作仅需执行一次。
右键单击任何报表对象，然后选择 “复制对象名称”。

将对象名称复制到剪贴板后，可以轻松地将其输入到 Windows 资源管理器或 Visual Studio Code 的搜索栏中，以查找或标识 PBIR 文件夹中的对象名称。

PBIR Json 架构

每个 PBIR JSON 文件都包含文档顶部的 JSON 架构声明。此架构 URL 可公开访问，可用于详细了解每个文件的可用属性和对象。此外，它还在使用 Visual Studio Code 等代码编辑器进行编辑时提供内置的 IntelliSense 和验证。

提示 PBIR JSON 架构工具提示的屏幕截图。

架构 URL 还定义了文档的版本，该版本预计会随着报表定义的发展而变化。

所有 JSON 架构均在此处发布。

PBIR 注释

对于每个 visual、page 和 report，都可以在报表定义中将注释包含为名称-值对。虽然 Power BI Desktop 忽略这些批注，但它们对于外部应用程序（如脚本）非常有用。

例如，可以在 report.json 文件中为报表指定 defaultPage，然后供部署脚本使用。

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/report/1.0.0/schema.json",
  "themeCollection": {
    "baseTheme": {
      "name": "CY24SU06",
      "reportVersionAtImport": "5.55",
      "type": "SharedResources"
    }
  },
  ...
  "annotations": [
    {
      "name": "defaultPage",
      "value": "c2d9b4b1487b2eb30e98"
    }
  ]
}

对 PBIR 文件的外部更改

可以在代码编辑器（如Visual Studio Code或其他外部工具）中编辑受支持的 PBIR JSON 文件，同时项目在 Power BI Desktop 中保持打开状态。保存文件时，Power BI桌面会检测更改并显示“应用外部更改”横幅。选择 “应用外部更改 ”以重新加载报表定义，而无需关闭并重新打开项目。

在外部编辑 PBIR 文件之前，请将任何更改保存在 Power BI Desktop 中。如果应用外部更改时Power BI桌面发生了未保存的更改，它会警告你，未保存的更改将被覆盖。有关完整的工作流和限制，请参阅Power BI桌面外部编辑 PBIP 文件。

PBIR 文件必须符合其 JSON 架构。 VS Code 可识别诸如属性名称不受支持的问题或不正确的属性类型：

提示 PBIR JSON 架构验证的屏幕截图。

应用更改或在 Power BI Desktop 中打开文件时，对 PBIR 内容的外部更改可能会导致错误。这些错误可以是两种类型：

阻止错误可防止 Power BI Desktop 加载报表更改。这些错误会指出问题以及在再次应用更改之前必须修复的文件：

显示 PBIR 阻止错误提示的屏幕截图。

诸如架构无效或缺少所需属性之类的错误会阻止错误。若要识别这些错误，请在 VS Code 中打开该文件并检查架构验证消息。

非阻塞错误不会阻止 Power BI Desktop 打开报表，并会自动得到解决。

提示框中 PBIR 非阻塞错误的屏幕截图。

无效的 activePageName 配置是 Power BI Desktop 可自动修复的非阻止性错误的一个示例。该警告使你有机会在保存报表并覆盖外部定义之前查看更正。

常见 PBIR 错误

场景：重命名视觉对象或页面文件夹名称后，打开报表时不再显示视觉对象或页面。

解决方案：验证名称是否符合命名约定。如果不符合，Power BI Desktop 将忽略文件或文件夹，并将其视为专用用户文件。

场景：新报表对象的名称与其他报表对象不同。例如，大多数页面文件夹都名为“ReportSection0e71dafbc949c0853608”，而少数文件夹名为“1b3c2ab12b603618070b”。

解决方案：PBIR 为每个对象采用了新的命名约定，但它仅适用于新对象。将现有报表保存为 PBIP 时，必须保留当前名称以防止中断引用。如果需要保持一致性，则允许使用脚本批量重命名。

场景：我复制了书签文件，保存后，删除了大部分书签配置。

解决方案： 此行为是预期行为，报表书签会保存报表页面及其所有可视化对象的状态。由于捕获的状态源自具有不同视觉对象的另一个报表页，因此任何无效的视觉对象都会从书签配置中删除。如果还复制该书签所依赖的视觉对象和页面，该书签将保留其配置。

场景：我从另一个报表复制了一个页面文件夹，并遇到一个错误，指出“'pageBinding.name'属性的值必须是唯一的。

解决方案：要支持钻取和页面工具提示，必须具有 pageBinding 对象。由于它们可能由其他页面引用，因此名称在报表中必须是唯一的。在新复制的页面上，分配一个唯一值来解决错误。 2024 年 6 月之后，这种情况不再是问题，因为 pageBinding 名称将默认是 GUID。

将现有报表转换为 PBIR

PBIR 已正式发布，是默认报表格式。你仍然可以在 Power BI Desktop 和 Power BI 服务中打开使用 PBIR-Legacy 的报表。编辑和保存 PBIR-Legacy 报表时，Power BI静默地将其转换为 PBIR。

在转换之前，Power BI创建报表的备份：

Power BI Desktop 在以下位置之一将备份保留 30 天：
- Microsoft应用商店版本： %USERPROFILE%\Microsoft\Power BI Desktop Store App\TempSaves\Backups
- 可执行安装程序版本： %USERPROFILE%\AppData\Local\Microsoft\Power BI Desktop\TempSaves\Backups
Power BI 服务会将 PBIR-Legacy 备份保留 28 天。若要还原它，请从工作区打开 报表设置 ，然后选择“ 还原为 PBIR-Legacy”。仅针对直接在 Power BI 服务中转换的报表创建此备份。

还原 PBIR-Legacy 备份并不会阻止再次转换。若要以 PBIR-Legacy 格式保留报表，请勿在Power BI 服务中编辑报表，或使用 2026 年 9 月之前发布的 Power BI Desktop 版本。

PBIR 注意事项和限制

请记住以下注意事项和限制：

只有在编辑报表时筛选器窗格至少展开一次后，视觉自动筛选器才会保存到 PBIR visual.json 文件中。
如果在编辑并保存报表时Power BI不会将 PBIR-Legacy 报表转换为 PBIR，则转换遇到产品问题。创建支持请求来报告问题。

服务强制实施的 PBIR 大小限制：

每个报表最多 1,000 页。
每个页面的最大视觉对象数为 1000。
每个报表最多 1,000 个资源包文件。
所有资源包文件的最大大小为 300 mb。
所有报表文件的最大大小为 300 mb。

重要

如果达到上述限制，应考虑优化报表。请参阅 Power BI 优化文档。

Fabric Git 集成和Fabric REST API使用 PBIR 导出报表定义。

反馈

此页面是否有帮助？

Last updated on 2026-09-29