Penpot 插件怎么从开发到部署上线（含 Netlify 部署与 CORS 处理）

Penpot 插件怎么从开发到部署上线（含 Netlify 部署与 CORS 处理）

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

你要完成的任务是：把一个 Penpot 插件从创建项目开始，经过本地加载验证，最终部署到 Netlify 这类静态托管平台，让用户在 Penpot 里通过 manifest URL 安装并使用它。核心前提是 Penpot 插件独立于 Penpot 主程序运行（运行在 iframe 中），必须自行托管、托管在 Penpot 环境之外。适用环境是 Node + npm（官方文档 FAQ 说明他们目前使用 Node v22.2.0），以及你熟悉的任意 JavaScript 框架或零框架。

本文路径基于仓库内文档 Getting started、Create a Plugin、Deployment、FAQ，以及仓库中的真实示例插件 colors-to-tokens-plugin。

准备条件

• 基本的 Penpot 使用经验，以及 JavaScript、HTML、CSS 基础；
• 已安装 Node 和 npm，推荐与官方一致的 Node v22.2.0（FAQ）；
• 一个文本编辑器或 IDE；
• 可选：Git 基础、TypeScript 基础、一个前端框架（Angular / React / Vue）经验、一个你选定的托管服务。

开发起点有两条路，二选一：

1. 使用官方模板：TypeScript 基础模板（Penpot Plugin Starter Template）或基于框架的模板（plugin-examples，含 Angular / Vue / React）。使用模板可以跳过下面的建项步骤，直接到“本地构建并在 Penpot 中加载验证”一节。
2. 用框架从零创建，文档给出的建项命令与示例版本（version we used in the examples）：

Framework	Command	Version*
Angular	ng new plugin-name	19.2.2
React	npm create vite@latest plugin-name -- --template react-ts	19.0.0
Vue	npm create vue@latest	3.5.13
Svelte	npm create svelte@latest	5.23.0

安装 Penpot 插件库

两个 npm 包支撑插件开发：

npm install @penpot/plugin-styles npm install @penpot/plugin-types

• @penpot/plugin-styles提供与 Penpot 界面一致的 UI 样式（非强制，但文档推荐使用，可帮助处理明暗主题），引入方式是全局 CSS 里：

@import "@penpot/plugin-styles/styles.css";

• @penpot/plugin-types提供 Penpot Plugin API 的类型定义，TypeScript 下能让编辑器自动补全并直接查看 API 文档。使用 TypeScript 时还要把它加入tsconfig.json的 typings：

{ "compilerOptions": { "typeRoots": ["./node_modules/@types", "./node_modules/@penpot"], "types": ["plugin-types"] } }

编写 plugin 文件与 manifest.json

plugin 入口文件

plugin.js/plugin.ts是你调用 Penpot API 的地方，通常放在src/下。可以这样起步：

penpot.ui.open("Plugin name", "", { width: 500, height: 600, });

尺寸是可选的，不指定时插件默认以 285x540 像素打开。只有这个文件里可以使用penpot对象，不要在插件界面脚本里调用。

manifest.json

manifest 提供插件元数据，必须放在能被 HTTP 访问的位置（文档建议public/目录）：

{ "name": "Plugin name", "description": "Plugin description", "version": 2, "code": "plugin.js", "icon": "icon.png", "permissions": [ "content:read", "content:write", "library:read", "library:write", "user:read", "comment:read", "comment:write", "allow:downloads" ] }

字段要点：

• "version": 2：当code和icon使用相对路径时必须设为 2，此时资源从 manifest 所在位置解析；省略则 Penpot 按 version 1 处理；
• permissions按需声明，常见的有content:read/content:write（读/写设计内容）、library:read/library:write（组件库）、user:read、comment:read/comment:write、allow:downloads（下载整个项目文件）、allow:localstorage（本地存储代理，注意用户可在浏览器中看到其中的数据）。写入权限自动包含对应的读取权限；
• icon建议 56x56 像素、正方形，插件管理器会自动缩放到 56x56；
• 插件名建议短小并带-plugin后缀，如shape-remover-plugin。

仓库中的真实示例可直接参考：colors-to-tokens-plugin 的 manifest.json（"version": 2，code指向assets/plugin.js，仅申请content:read、library:read、allow:downloads）。

CORS 处理：_headers 文件

插件运行在 iframe 里、由 Penpot 页面加载跨域资源，无论是本地测试还是线上部署都可能遇到 CORS 问题。文档给出的统一方案是在插件工程里加一个_headers文件，放在public/文件夹或与主文件同级：

/* Access-Control-Allow-Origin: *

仓库示例插件中对应的真实文件是 src/_headers，内容是在上述基础上额外声明了Access-Control-Allow-Methods: GET, POST, OPTIONS和Access-Control-Allow-Headers: Content-Type。本地在https://penpot.app/上调试插件时同样适用这套跨域头。

本地构建并在 Penpot 中加载验证

让 plugin 文件可被 HTTP 访问

src/plugin.ts无法直接通过http://localhost:XXXX/plugin.js访问，需要构建或搬运。文档给出两种做法：

Vite 方案：在vite.config.ts中把插件入口加入 rollup 输入（下面的[...]代表你工程已有的其他配置，XXXX替换为你的预览端口）：

export default defineConfig({ build: { rollupOptions: { input: { plugin: "src/plugin.ts", index: "./index.html", }, output: { entryFileNames: "[name].js", }, }, }, preview: { port: XXXX, }, });

并在package.json中加入：

"scripts": { "dev": "vite build --watch & vite preview", "build": "tsc && vite build" }

Esbuild 方案（your-folder替换为你的实际目录）：

npm i -D esbuild esbuild your-folder/plugin.ts --minify --outfile=your-folder/public/plugin.js

注意 esbuild 方案下，serve 过程中修改了 plugin 文件需要重新构建。如果整个插件就是纯 JavaScript，也可以直接把plugin.js放进public/目录，跳过本步。

加载到 Penpot

启动本地服务后，先确认两个地址都能访问：

• http://localhost:XXXX/manifest.json
• http://localhost:XXXX/plugin.js

如果文件在子目录里，URL 相应调整（如http://localhost:XXXX/folder/manifest.json）。

然后在 Penpot 中打开插件管理器：任意项目内按Ctrl + Alt + P（macOS 为⌘ + Alt + P），或从菜单、工具栏打开：

在弹窗中填入 manifest 的 URL 即可安装；安装成功后即可随时启动插件。

构建产物

部署前执行构建（build脚本需已在package.json中配置）：

npm run build

产物默认在dist/目录（除非你配置了别的输出位置）。注意有些框架的构建器会多套一层目录，文档举了apps/project-name/、project-name/或browser/这类情况，上传/拖拽时要找到真正含manifest.json的那一层。

用 Netlify 部署上线

方式一：连接 Git 仓库（文档主路径）

1. 注册 Netlify 账号（支持 GitHub、GitLab、Bitbucket 或邮箱方式）；
2. 进入 Netlify 的 Start 入口，选择 Connect to Git，把你的插件仓库接入，并授权 Netlify 安装到全部或指定项目；
3. 配置构建设置：Netlify 会自动检测框架并给出基础配置，文档说明“通常已经够用”；
4. 执行 Deploy。

部署前记得工程里已有上面的_headers文件，随构建一起发布即可解决 CORS。

方式二：Netlify Drop 拖拽上传（可选分支）

1. 本地执行npm run build；
2. 打开 Netlify Drop 拖拽部署页；
3. 把包含主文件的那个文件夹拖入。文档特别提醒：直接拖整个dist可能不生效，应拖实际存放manifest.json等主文件的那一层；
4. 完成。

文档同时还介绍了 Cloudflare（Git 接入或直接上传）和 Surge（CLI 部署，CORS 用public/CORS文件内容为*实现）两个备选托管平台，作为可选分支了解即可，主路径仍是上面的 Netlify。

上线后验证与常见问题

上线后的验证方式与本地一致：在 Penpot 插件管理器里填入线上的 manifest URL（形如https://yourdomain.com/assets/manifest.json，注意要指向 manifest.json 文件本身而不是站点根路径）并安装，能打开插件即成功。

FAQ 给出了一个典型的失败现象与判断方向：

• “插件在本地能跑，装不上 Penpot”：检查你在插件管理器里填的 URL 是否形如https://yourdomain.com/assets/manifest.json，即能直接解析到 manifest 文件；
• 插件名称应短小并以-plugin结尾；
• 图标不强制尺寸，会被自动调整为 56x56，保持正方形即可。

提交到 Penpot 插件目录（可选）

完成部署后，想让更多用户发现插件，可以通过 Penpot Hub 的插件提交页（penpot.app 站内）填写插件详情提交到官方目录；一旦上架，任何 Penpot 用户都可以安装使用。

限制说明

• 目前所有插件都必须独立托管在 Penpot 环境之外，没有例外；
• Figma 插件不能迁移到 Penpot，两者功能集不同、不兼容；
• 没有强制的安全或质量规范，但官方建议使用 eslint 或 prettier；
• 遇到问题可以向文档中给出的 [e-mail] 反馈。

深入 API 用法可继续读 API 文档 和 示例与模板。

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