Windows下用Vue搭建Adobe UXP插件开发环境全流程

想在Adobe系的软件里写自己的插件翻来覆去搜出来的教程可能还停留在CEP时代的老路子上。Adobe这些年把插件开发框架从CEP迁到了UXP生态和工程方式都变了。这篇文章是Windows平台上从零搭建UXP插件开发环境并用Vue写完第一个插件并成功试运行的完整记录。不敢说覆盖所有坑但环境搭建、Vue工程接入、宿主API调用、运行调试这条链路我可以保证是实际跑通过、并且很多细节是百度不到的经验。适合这几类人看刚接触Adobe插件开发、想用Vue/React这类现代前端框架干活、或者之前被CEP折磨过想换新方案的朋友。文章不会只贴几个命令就完事我会把每个关键步骤背后的选择逻辑也讲清楚。1. 先想明白UXP和CEP的区别再决定要不要换赛道1.1 CEP到底差在哪老一代CEPCommon Extensibility Platform的做法是在Adobe宿主应用里内嵌一个CEFChromium Embedded Framework浏览器插件面板本质就是一个网页开发时可以用很完整的浏览器环境。听起来很美但实际用起来问题不少资源占用高。每打开一个面板宿主进程就被拖累PS、AI这类本身内存大户再叠几个CEF16G内存都能报警。宿主兼容性不稳定。不同宿主、不同版本捆绑的CEF版本不一致经常出现这个版本能跑、换了版本就白屏。开发调试割裂。CEP插件需要用专门的工具去连调试端口或者用老旧的模拟环境整个体验和现代Web开发差着辈分。我早期做AI插件的时候就吃过这个亏面板里一个简单的input在Windows上某个版本突然获取不到焦点排查一整天发现是CEF内部bug。这种问题基本无解只能绕。1.2 UXP给插件开发带来了什么UXPUnified Extensibility Platform是Adobe自己实现的Web运行时目标是把插件引擎统一成一套。它不依赖完整的浏览器内核而是内嵌一个精简的运行时加载速度更快、内存占用更低同时提供了相对统一的宿主API接口。UXP带给开发者最直观的变化开发语言还是Web那一套HTML、CSS、JavaScript上手成本低。内置模块机制通过require(photoshop)、require(illustrator)这类内置模块访问宿主能力不用像CEP那样通过共享内存来回通信开发体验更像写Node.js。调试体验接近现代Web配合UXP Developer Tool能用上Chromium DevToolsconsole、断点都能用。工程化友好因为本质是Web技术Vue、React、Vite这些前端工具链理论上都能接入。当然UXP不是万能的很多底层能力还在快速迭代某些浏览器API在UXP里并不存在。所以越早动手越能提前摸清边界。提示文章后面的示例我会以Photoshop作为宿主应用来演示。核心流程换到Illustrator、InDesign时基本一致只有manifest里的宿主标识需要改。1.3 哪些宿主应用已经支持UXP目前UXP主要覆盖这些Adobe产品宿主应用关键版本要求UXP支持程度Photoshop22.0及以上较完善适合入门Illustrator27.0及以上较完善InDesign17.0及以上可用界面类功能支持较好Premiere Pro / After Effects较新版本逐步开放XD早期UXP试验田已被官方逐步定调迁移到新方案我的建议是如果你是第一次尝试UXP直接用最新版Photoshop资料多、API稳定、网上踩坑案例也多。别拿老版本宿主硬试否则会出现manifest明明没问题却加载失败的情况。2. 环境准备三个环节缺一不可2.1 Node.jsVue工程的地基UXP插件本身不需要Node.js但只要你打算用Vue、Vite这套工程链Node.js就是必须的。安装时直接选LTS版本我用的是18Vite、Vue 3对这个版本支持得很稳。装完在CMD或PowerShell里确认一下node -v npm -v能正常输出版本号说明Node环境没问题。我特别提醒一个Windows上的习惯性动作安装路径不要带中文。很多人默认C盘用户名是中文后面npm install报各种莫名依赖错误十有八九和路径编码有关。实在躲不开中文用户目录就手动把Node安装到一个纯英文路径下。2.2 UXP Developer Tool调试和加载的核心UDTUXP Developer Tool是Adobe官方提供的桌面工具功能就几个加载插件文件夹、启动宿主应用、打开调试工具、把插件注册到宿主里。下载渠道就是Adobe开发者官网安装过程无脑下一步。装完打开后界面很克制最显眼的是插件列表和右侧操作按钮。UDT本身不负责写代码它的定位更像一个“桥接器”把你的插件源码和真正的宿主应用连接起来。后面试运行环节你会发现所有关于加载、重启、调试的操作都离不开它。提示第一次使用UDT建议先打开Adobe Creative Cloud Desktop并登录Adobe账号。否则UDT启动宿主应用时可能遇到授权问题。2.3 宿主应用的版本检查别直接装个旧版PS就开始鼓捣UXP插件对宿主版本是有硬性要求的。在PS里打开“帮助→关于Photoshop”看版本号确认不低于22.0。如果可以最好用2022年之后的版本。原因很直接UXP的API还在快速迭代新版本宿主不仅支持的API更全修复的运行时问题也多。你不想辛辛苦苦写完面板结果因为宿主少支持一个API而全盘无用。完成这一步你的机器上应该有Node.js、UDT、Adobe宿主应用。三样齐了可以正式开始。3. 不掺Vue先让一个裸插件在宿主里跑起来很多新手一上来就急着把Vue工程堆上去结果环境、manifest、宿主版本之间出了交叉问题根本不知道是哪一环崩溃的。我的建议是先做一个不包含任何框架的最简插件先验证“UXP插件能加载、能显示面板、能调用宿主API”这条原始链路是通的然后再把Vue接进来。这样排错范围一下子就缩小了。3.1 手工搭建最小插件目录和manifest.json在电脑上建一个空目录比如D:\dev\uxp-html-demo里面创建uxp-html-demo/ ├── manifest.json ├── plugin.js └── index.htmlmanifest.json是最核心的文件它告诉UDT和宿主应用这个插件是什么、长什么样、能干什么{ id: com.example.uxphtmldemo, name: UXP HTML Demo, version: 1.0.0, main: plugin.js, manifestVersion: 5, host: [ { app: PS, minVersion: 22.0.0 } ], entrypoints: [ { type: panel, id: helloPanel, label: Hello UXP Panel, url: index.html, defaultSize: { width: 320, height: 240 } } ] }逐字段说下关键点id插件全局唯一标识建议用反向域名风格避免和别人插件冲突。main插件主入口脚本文件。manifestVersion固定为5这是当前UXP的清单版本。host数组可以声明这个插件支持哪些宿主应用。app: PS代表Photoshop这是Adobe官方的缩写约定。entrypoints声明插件的入口点。type: panel表示这是一个面板插件id会被后面plugin.js用到必须保持一致url指向面板要加载的HTML文件。defaultSize面板默认宽高单位是像素。这里最容易搞错的是entrypoints.panels里的id和plugin.js中panels对象属性的对应关系。两者不一致面板就会加载失败。3.2 入口脚本与面板HTML要处理的几个细节plugin.js的职责是注册插件的生命周期回调。最小示例长这样const { entrypoints } require(uxp); entrypoints.setup({ plugin: { async create(plugin) { console.log(插件创建成功:, plugin.name); }, async show(plugin) { console.log(插件面板显示); }, async hide(plugin) { console.log(插件面板隐藏); } }, panels: { helloPanel: { show(event) { console.log(helloPanel 显示); }, hide(event) { console.log(helloPanel 隐藏); } } } });重点解释一下为什么panels对象的key是helloPanel。它必须和manifest里entrypoints数组里id字段一模一样。UDT加载插件时运行时就是靠这个对应关系知道哪个面板绑定哪段逻辑。index.html的底子要留好Vue挂载点后面会用到!DOCTYPE html html head meta charsetutf-8 titleUXP HTML Demo/title /head body div idapp h1原生HTML插件面板/h1 button idbtnAlert弹出宿主提示/button /div script const { app } require(photoshop); document.getElementById(btnAlert).addEventListener(click, () { app.showAlert(第一个UXP插件跑通了); }); /script /body /html注意这里直接用了require(photoshop)这是UXP运行时提供的宿主API模块。在浏览器里这是不存在的只有宿主加载插件时才有。这就是为什么开发UXP插件和普通网页开发的运行时环境有微妙差异。3.3 UDT加载与启动的完整操作打开UDT按下面顺序操作点击左侧或顶部的Add Plugin选择D:\dev\uxp-html-demo这个包含manifest.json的目录不要选错层级。插件会出现在列表里点击右侧的Load按钮UDT会校验manifest任何一个字段写错都会在这里报错。点击Launch按钮UDT会弹出选项让你选择启动哪个宿主应用选Photoshop。Photoshop打开后顶部菜单栏或者窗口→扩展里找到Hello UXP Panel点击就能看到面板。如果一切正常点击面板里的按钮Photoshop会弹出提示框同时UDT的日志区域或DevTools里能看到插件创建成功和helloPanel 显示的日志。走到这一步说明你的UXP环境链路完全通了接下来才适合把Vue正式请进来。4. 用Vite把Vue3接进UXP插件4.1 为什么不用CDN直接用Vue理论上你可以直接在index.html里放一个script srcvue.global.js/script然后用全局Vue对象开发。这种方案对原型验证很快但实际项目不建议完整版Vue包含模板编译器体积大UXP面板是常驻内存的能省则省。没有SFC单文件组件组件化开发成了一纸空谈。资源管理、样式隔离、代码复用都很难受。所以更合理的思路是用Vite把Vue工程构建成静态文件UXP面板再加载这些静态文件。Vite只负责UI层UXP负责宿主API层两边互不干扰问题边界也清晰。4.2 项目目录调整与vite.config.js的UXP专用配置我在前面那个插件目录里重建一下结构让它同时成为Vite项目根目录uxp-vue-demo/ ├── src/ # Vite源码 │ ├── main.js │ └── App.vue ├── package.json ├── vite.config.js ├── manifest.json ├── plugin.js ├── host-api.js ├── index.html └── dist/ # npm run build输出 ├── main.js └── style.csssrc/main.js是Vue应用的入口import { createApp } from vue; import App from ./App.vue; createApp(App).mount(#app);src/App.vue先写一个最简单的组件验证Vue能正常渲染template div h1Vue UXP 试运行/h1 p{{ message }}/p /div /template script setup import { ref } from vue; const message ref(Vue 组件已经成功挂载); /script style scoped h1 { font-size: 16px; } p { font-size: 13px; color: #666; } /style真正关键的是vite.config.jsimport { defineConfig } from vite; import vue from vitejs/plugin-vue; export default defineConfig({ plugins: [vue()], base: ./, build: { outDir: dist, emptyOutDir: true, lib: { entry: src/main.js, formats: [iife], name: VueUxpPlugin, fileName: () main.js } } });说下这份配置背后的理由base: ./让构建产物里所有资源路径都变成相对路径。UXP面板加载HTML时不是标准http服务绝对路径很容易404。lib.formats: [iife]IIFE格式会把所有模块打包成一个自执行脚本UXP面板的script src能直接加载。不用ES Module的原因很简单UXP运行时对ESM的支持并非所有版本都一致IIFE是最保险的兼容方式。fileName: () main.js固定出口文件名避免每次构建都生成带hash的名字省得每次都要手动改index.html里的引用路径。package.json里的scripts配置{ name: uxp-vue-demo, version: 1.0.0, private: true, scripts: { dev: vite, build: vite build }, dependencies: { vue: ^3.4.21 }, devDependencies: { vitejs/plugin-vue: ^5.0.4, vite: ^5.2.0 } }dev命令在这里用途有限因为UXP面板加载的是本地HTML不是DevServer。但写Vue组件时如果你想单独调试UI效果npm run dev还是有用的。4.3 宿主API层的隔离设计host-api.jsVue组件里能不能直接require(photoshop)能但强烈不建议。原因有两方面。第一require是UXP运行时注入的CommonJS能力Vite构建时遇到这种非标准调用处理不好会直接构建失败第二UI层和宿主API层耦合在一起后面要支持多个宿主应用、或者要Mock数据做单元测试会很难受。我把宿主API单独封装到host-api.jsexports.getDocumentName function () { const { app } require(photoshop); if (app.activeDocument) { return app.activeDocument.name; } return 当前没有打开的文档; }; exports.showHostAlert function () { const { app } require(photoshop); app.showAlert(来自Vue组件的宿主API调用); };在plugin.js里把host-api.js挂到全局const { entrypoints } require(uxp); const hostApi require(./host-api.js); globalThis.hostApi hostApi; entrypoints.setup({ plugin: { async create(plugin) { console.log(插件创建成功:, plugin.name); } }, panels: { vuePanel: { show(event) { console.log(vuePanel 显示); } } } });globalThis.hostApi是跨UXP运行时和Vue组件通信的桥梁。UXP里的require(./host-api.js)会把整个对象挂到全局Vue组件里就可以安全地访问。在App.vue里使用template div h1Vue UXP 试运行/h1 p{{ message }}/p button clickreadDocumentName读取文档名/button button clickhostAlert调用宿主提示/button /div /template script setup import { ref } from vue; const message ref(点击按钮读取当前文档信息); function readDocumentName() { if (globalThis.hostApi) { message.value globalThis.hostApi.getDocumentName(); } else { message.value hostApi 未挂载请检查 plugin.js; } } function hostAlert() { if (globalThis.hostApi) { globalThis.hostApi.showHostAlert(); } } /script我额外做了一层globalThis.hostApi的存在性判断。原因是很现实的问题UXP运行时加载plugin.js和加载面板HTML这两件事在不同版本里时序可能有一点点差异偶尔会出现Vue组件已经执行、但hostApi还没挂到全局的情况。加个判断反而能及时发现是哪一侧出了问题而不是面板白屏后无从下手。4.4 构建产物与插件页面的整合在插件根目录执行npm install npm run build构建完成后dist/里会生成main.js和style.css两个文件。接着把插件根目录的index.html改成加载Vite产物!DOCTYPE html html head meta charsetutf-8 titleVue UXP Demo/title link relstylesheet hrefdist/style.css /head body div idapp/div script srcdist/main.js/script /body /html这里和之前的裸插件有个明显区别div idapp不需要任何内容Vue会把组件完整渲染到里面。打开UDT把插件目录切换成新的uxp-vue-demo重新Load再Launch启动Photoshop。面板打开后你会看到Vue渲染出来的完整UI点击按钮能读取当前PS文档名称、能弹出宿主提示。用Vue写UXP插件的主流程到这里就跑通了。5. 试运行验证和常见问题的排查链路5.1 从Launch到面板显示逐节点对症状试运行如果失败先别急着改代码。把链路拆开看每个节点都有对应的典型症状链路节点典型症状优先排查方向UDT加载manifest插件条目变红或报格式错误manifest JSON语法、id合法性UDT Launch宿主选中宿主后启动失败Adobe账号登录、宿主版本过低宿主内加载plugin.js面板菜单里根本没有你的插件host数组的app缩写和minVersion面板HTML加载菜单里能看到插件但点开是空白index.html路径、script引用路径Vue脚本执行空白面板且日志里有JS报错dist文件是否存在、IIFE是否正常执行hostApi调用按钮点击无反应或报undefinedplugin.js是否执行、globalThis挂载我每次遇到问题都会按这个表格逐层检查而不是上来就怀疑Vue配置。5.2 高概率踩中的报错与根因这里整理几个最常见的问题每个都是我实际遇到过的。问题1UDT提示“This plugin requires a newer version of Photoshop”manifest里host.minVersion写了22.0.0而你的Photoshop版本低于这个值。要么升级宿主要么把minVersion调低到当前宿主能接受的版本。注意不能低于UXP真正支持的版本否则运行时会出更隐蔽的bug。问题2面板加载出来是空白DevTools里看不到任何报错这种最迷往往不是代码问题而是构建出来的dist/main.js没有按预期生成。我遇到过Vite配置里emptyOutDir: true把整个dist清空后构建中断结果面板引了个空文件。先去资源管理器看dist目录里有没有main.js和style.css文件大小是否正常。然后在面板空白处右键检查看到JS文件404就是引用路径问题。问题3globalThis.hostApi is undefined先确认plugin.js到底有没有被执行。在plugin.js的create回调里加一行console.log(plugin.js executed)然后看UDT的日志。如果这条日志都看不到说明manifest的main字段指向错误或者插件根本没被重新加载。如果日志看得到但hostApi还是undefined检查require(./host-api.js)的路径UXP对相对路径的大小写很敏感。问题4Vue构建产物里出现“require is not defined”这通常是因为你在Vue组件源码里直接用了require(photoshop)Vite在构建时保留了CommonJS调用但插件里的执行环境和预期不一致。解决方案就是回到第4章的方案把宿主API调用全部放host-api.jsUI层绝不直接require宿主模块。问题5样式全部丢失或者scoped样式不生效先看index.html里有没有引用dist/style.css再确认Vite的lib模式有没有把CSS提取出来。lib模式下如果你组件里用的是普通全局样式有些版本不会自动打包进style.css需要手动import一个src/style.css入口。5.3 代码改动后的重载与验证流程UXP插件开发时改代码不像普通网页那样刷新一下就好有一个固定节奏修改src/App.vue或Vue组件代码。在插件根目录执行npm run build。回到UDT点击插件条目右侧的重载Reload按钮。切到Photoshop关掉面板再重新打开或者在面板里看DevTools里的变化。为什么必须关掉重开UXP面板在宿主里是有生命周期的光刷新HTML不一定能触发show事件关掉重开才能保证重新走一遍完整的挂载链路。验证时最直观的方法是在App.vue的onMounted周期里打日志import { onMounted } from vue; onMounted(() { console.log(Vue组件已挂载hostApi存在, !!globalThis.hostApi); });日志能在UDT打开的DevTools控制台里看到。日志顺序和内容能一次性确认三件事面板HTML加载了、Vue的main.js执行了、hostApi已经能访问了。看到“hostApi存在true”再去做宿主API调用基本稳了。最后再分享一个实际项目里的习惯UXP加Vue这套组合最舒服的状态是把Vite玩成一个纯粹的静态站点生成器不要让它承担任何宿主相关的逻辑。我会在src里把Vue组件目录、状态管理、样式模块都按Web前端标准拆好宿主API层单独放一个文件夹用的时候通过globalThis.hostApi桥接。前端界面和宿主能力彻底分家之后我能同时维护三套插件UI而只改一份host-api逻辑也能在浏览器里用DevServer单独调试UI样式调试效率比早期CEP时代高了一个量级。另外强烈建议养成看UDT日志的习惯很多问题不是代码报错而是加载时序和资源路径问题日志比UI白屏可靠得多。每次改动后先看日志再操作界面能省掉大量瞎猜的时间。写到这里Windows下用Vue开发UXP插件从环境搭建到试运行的全链路就完整了。真遇到我上面没提到的新坑欢迎按第5章的排查链路一层层拆解大部分问题都能定位到具体节点。