企业官网建设流程全解析

如何查看 .penpot 文件内部结构并用 File Inspector 检查设计数据

【免费下载链接】penpotPenpot: The open-source design platform for Product teams that need scalable collaboration.项目地址: https://gitcode.com/GitHub_Trending/pe/penpot

Penpot 的原生文件格式.penpot不是黑盒：它是一个 ZIP 压缩包，里面是人类可读的 JSON 元数据（页面、形状、颜色、组件）加上二进制媒体文件（图片、字体）。当你需要备份设计文件、核对一个导出包里到底包含哪些页面和形状、或者排查媒体引用问题时，可以拆包直接查看。本文的目标是：先通过命令行确认.penpot压缩包的结构与清单，再用 Penpot 官方的 Penpot file inspector 页面交互式地检查设计数据、跨文件引用和媒体资源。前提是你手里有一个.penpot文件，且它由当前版本的 Penpot 导出（当前所有版本都导出为 v3 格式，即 ZIP + JSON）。

准备一个 .penpot 文件

如果还没有现成的导出文件，可以从 Penpot 里导出单个文件（参见 Export and import Penpot files）：

• 从 dashboard：在文件卡片的菜单里选择 download 选项。
• 从 workspace：在主菜单里选择 download 选项。

如果文件关联了共享库（Shared libraries），导出时会出现三种方式，会影响包里包含哪些资源：

• Export shared libraries：共享库会一并导出并保持链接关系；
• Include shared library assets in file libraries：把外部库资源合并进文件自身的库；
• Treat shared library assets as basic layers：不导出共享库，库资产降级为普通图层。

需要核对库资源时，选前两种；只想检查文件本体时选第三种。

.penpot 压缩包里有什么

把.penpot文件解包后，会看到这样的结构（来自格式说明，目录中的{file-id}等是文件实际 UUID）：

your-design.penpot (ZIP archive) ├── manifest.json ← Table of contents ├── files/ ← Your design data │ ├── file-metadata.json │ └── file-data/ │ ├── pages/ ← Each page of your design │ ├── colors/ ← Library colors │ ├── components/ ← Library components │ ├── typographies/ ← Library typographies │ ├── tokens.json ← Design tokens │ └── media/ ← Media references └── objects/ ← Images and binary assets

更完整的目录定义见技术规格：files/{file-id}.json是文件元数据，files/{file-id}/pages/{page-id}.json是页面元数据，files/{file-id}/pages/{page-id}/{shape-id}.json是每个单独的形状，files/{file-id}/media/、colors/、components/、typographies/存放库资源，objects/下每个二进制文件（png、jpg、svg 等）都配有一个同名的{uuid}.json元数据文件。

manifest.json是整包的目录清单，记录：使用的格式版本、创建文件的 Penpot 版本、包含哪些文件、启用了哪些特性（feature flags）。文档中给出的 manifest 示例如下（文档示例，实际值随你的文件变化）：

{ "type": "penpot/export-files", "version": 1, "generatedBy": "penpot/2.12.0-RC1-99-g40c27591f", "refer": "penpot", "files": [ { "id": "73b59a94-3ea3-8189-8007-3d36adc8c3e3", "name": "Pencil | Penpot Design System", "features": [ "fdata/path-data", "design-tokens/v1", "variants/v1", "layout/grid", "components/v2", "fdata/shape-data-type" ] } ], "relations": [] }

文件内部有两类版本号，看到时不要混淆：manifest.json里的format version跟踪 ZIP 结构本身的变化（当前为1）；每个文件 JSON 里的data version跟踪数据模型的变化，会随 Penpot 演进而增大。features字段则是特性开关列表，例如design-tokens/v1（使用设计令牌）、components/v2（v2 组件系统）、variants/v1（组件变体）、layout/grid（网格布局），导入方据此判断需要支持哪些能力。

用命令行查看结构（macOS / Linux）

.penpot就是标准 ZIP，用常规工具即可检查。以下命令中your-design.penpot是文档使用的示例文件名，请替换成你的实际导出文件名和路径；/tmp/penpot-inspect是文档给出的临时解包目录，解包命令会在此创建目录并写入文件。

# 1. 不解包，先列出包内文件清单 unzip -l your-design.penpot # 2. 解包到临时目录 unzip your-design.penpot -d /tmp/penpot-inspect # 3. 查看 manifest（需要系统已安装 jq，用于格式化 JSON 输出） cat /tmp/penpot-inspect/manifest.json | jq . # 4. 浏览整体目录结构（需要 tree 工具） tree /tmp/penpot-inspect # 5. 查看具体形状文件 cat /tmp/penpot-inspect/files/*/pages/*/*.json | jq .

如果不想逐条执行，技术规格还给了一个一键检查脚本，它只检查你传入的那一个文件，按顺序输出 manifest、文件列表、页面列表和媒体文件数量。说明副作用：脚本会用mktemp -d创建一个临时目录，结束时用rm -rf "$TMPDIR"删除该目录（只删除自己刚创建的目录）；需要在装有unzip和jq的 bash 环境下运行：

#!/bin/bash # Inspect .penpot file structure FILE=$1 TMPDIR=$(mktemp -d) unzip -q "$FILE" -d "$TMPDIR" echo "=== Manifest ===" cat "$TMPDIR/manifest.json" | jq '{type, version, files: [.files[] | {id, name}]}' echo -e "\n=== Files ===" for f in "$TMPDIR"/files/*.json; do echo "- $(jq -r '.name' "$f")" done echo -e "\n=== Pages ===" for f in "$TMPDIR"/files/*/pages/*.json; do echo "- $(jq -r '.name' "$f")" done echo -e "\n=== Storage Objects ===" ls -lh "$TMPDIR"/objects/*.{png,jpg,svg} 2>/dev/null | wc -l echo "media files" rm -rf "$TMPDIR"

在 Windows 上没有 unzip 命令时，操作路径是：右键.penpot文件选择 "Extract All..."（或使用 7-Zip）解包，浏览解出的文件夹查看结构，再用文本编辑器或 JSON 查看工具打开任意 JSON 文件。

用 Penpot File Inspector 检查设计数据

命令行适合快速确认结构；要逐层查看设计数据，用官方的 Penpot file inspector（Penpot 文档站 Technical guide → Developer → Data model 下的 "Penpot file inspector" 页面，工具直接嵌在该页面里）。它是一个纯浏览器静态页面，没有后端：

• 你的文件不会上传到任何服务器，全部处理都在浏览器内完成；
• 页面唯一的网络请求是在首次上传文件时从cdn.jsdelivr.net加载 JSZip 库。

操作步骤：

1. 打开 File Inspector 页面，把.penpot文件拖入上传区，或点击选择文件。页面标注支持.penpot（v3 ZIP format）；
2. 加载完成后，状态栏会显示Loaded <N> files from <文件名>，说明解包和索引成功，这是文件被正确读取的判断依据；
3. 默认进入File overview，顶部是一组概览卡片：Version、Generator、Files（文件数与前几个文件名）、Pages、Shapes、Library assets（颜色/组件/字体的数量）、Storage objects（对象数与总大小）、Media types（按 MIME 统计）；如果 manifest 里存在relations，还会列出 "Library dependencies"（文件与库的依赖关系）。下方 "Quick links" 可直接跳到manifest.json、文件元数据和媒体文件；
4. 左侧是完整的文件树（可按名称过滤），顶部搜索框可输入包内文件的完整路径直接 Open，← Overview按钮返回概览。

选中不同类型的文件时，Inspector 的展示方式不同：

• 形状文件（files/{file-id}/pages/{page-id}/{shape-id}.json）：顶部先给出一张 shape 卡片，汇总id、position、size、rotation、opacity、fills（带颜色色块）、strokes、文本预览（content.text截取前 100 字符）；图片形状还会显示媒体缩略图。卡片下方是带语法高亮的完整 JSON 树，工具栏支持按 key/值搜索高亮、按深度展开（Expand to depth，默认 2）、Collapse all。JSON 里的type字段标识形状类型，文档定义了 9 种：frame、group、rect、circle、path、text、image、bool、svg-raw。技术规格中给出的一个形状文件示例如下（文档示例，实际值随你的文件变化）：

  { "id": "260aea33-4e55-808c-8007-3d4f2efe4230", "name": "Rectangle", "type": "rect", "x": 100, "y": 100, "width": 200, "height": 150, "selrect": { "x": 100, "y": 100, "width": 200, "height": 150 }, "points": [ {"x": 100, "y": 100}, {"x": 300, "y": 100}, {"x": 300, "y": 250}, {"x": 100, "y": 250} ], "transform": [1, 0, 0, 1, 0, 0], "transformInverse": [1, 0, 0, 1, 0, 0], "parentId": "00000000-0000-0000-0000-000000000000", "frameId": "00000000-0000-0000-0000-000000000001", "fills": [ { "color": "#FF5733", "opacity": 1 } ], "r1": 8, "r2": 8, "r3": 8, "r4": 8 }

• JSON 文件通用：所有 UUID 值都是可点击的交叉引用，点击会跳转到引用目标文件；文件底部还有 "Referenced by (N)" 反向链接区，列出所有引用当前文件id的其他文件。这让你能在形状、组件、颜色、媒体之间双向导航。

• 图片与字体（objects/下的二进制文件）：显示预览图（字体则显示文件名）、name、size、mime，二进制文件提供 Download 链接；媒体文件会关联其media/{media-id}.json元数据，并显示 "Referenced by" 指向引用它的媒体 JSON。

• 其他二进制文件：显示文件名、大小、类型和 Download 链接。

文档中列出的错误现象及含义：

• Failed to load: <message>——ZIP 解包失败（文件不是有效的 ZIP/.penpotv3 包时会出现）；
• Failed to parse JSON: <message>——某个 JSON 文件内容无法解析；
• UUID <uuid> is referenced but no matching file was found in the archive.——点击了一个在包内找不到对应文件的 UUID 引用，说明该引用指向的资源不在当前压缩包中（例如导出时选择了不把共享库资产并入文件）。

结果核对与适用边界

检查是否成功的判断依据都来自文档：命令行下unzip -l能列出manifest.json、files/、objects/等条目；File Inspector 状态栏显示Loaded <N> files from <文件名>，且概览卡片中的Pages、Shapes、Storage objects数量与包内容对应（这些是 Inspector 统计出来的数值，随文件不同而变化，不是固定预期值）。

适用边界：

• File Inspector 只支持v3 ZIP 格式。.penpot格式演进历史为：v1（自定义二进制格式，已废弃，但仍可导入任何 Penpot 版本）、v2（SQLite 格式，从未对外发布）、v3（ZIP + JSON，当前）。旧版本 Penpot（2.3 及更早）导出的 v1 二进制文件不是 ZIP 包，本文的命令行拆包和 File Inspector 流程都不适用；
• manifest.json的version字段当前为1，generatedBy字段会告诉你导出文件的 Penpot 版本，可与你的环境对照；
• 文档还提到一条可选路径：Penpot MCP server 也可以用 AI 辅助读取和分析.penpot文件，适合自动化场景，本文不展开。

下一步

如果你的目的不是查看而是开发，技术规格给出了包内每个 JSON 文件的完整字段定义（manifest、file、page、shape、component、color、typography、tokens、storage object、media），并注明各 schema 在源码中的位置（如backend/src/app/binfile/v3.clj的 manifest schema）；Data model则提供 Penpot 数据结构的概念总览。

【免费下载链接】penpotPenpot: The open-source design platform for Product teams that need scalable collaboration.项目地址: https://gitcode.com/GitHub_Trending/pe/penpot