做 Adobe 生态的插件开发早几年绕不开 CEP最近两年风向明显变了Adobe 把新能力都往 UXP 上推。我刚接触 UXP 时第一反应是“这不就是换个壳的网页开发吗”真正在 Windows 上把环境搭起来、用 Vue 把面板跑起来才发现里面的门道比想象中多。Adobe Photoshop 的插件开发从 CEP 过渡到 UXP本质是从“旧浏览器 Node 环境”转向“受限 Chromium 沙箱”这个转变对前端开发者太友好了因为技术栈终于可以现代化了但踩坑方式也变了。这篇文章我会按实际开发顺序完整记录在 Windows 环境下怎么搭建一套基于 Vue 的 UXP 插件开发环境从 Node 版本选择、UDT 工具安装、Vue 项目初始化、manifest 配置到构建产物加载进 Photoshop 里真正运行起来最后把调试经验和常见报错一并整理出来。如果你之前只写过普通 Web 前端想试试 Adobe 插件开发或者已经写过 CEP 插件想迁移到 UXP这篇应该能帮你少走不少弯路。1. 项目背景与整体思路1.1 UXP 不是 CEP 换个马甲先把这个事情说清楚UXPUnified Extensibility Platform统一可扩展平台和 CEPCommon Extensibility Platform是两代完全不同的插件架构不是简单升级。CEP 基于老版 Chromium嵌入 Node.js 作为后端插件可以直接操作本地文件、启动子进程能力大得离谱但也正因为能力太强插件安全审查、崩溃隔离都很难做。UXP 的设计思路做了个大转向渲染层仍然是 Chromium 内核但运行环境变成沙箱化的没有 Node.js没有自由的本地文件访问所有能力都要通过 Adobe 暴露的 UXP API 来调用。用生活里的话说CEP 像把租客房卡直接办成了万能钥匙UXP 则是物业发的访客门禁卡能进哪些楼层、哪些房间都由物业后台控制。这个设计对用户更安全对开发者来说是约束但换来的是更现代、更统一的开发体系。Adobe 的目标是把 PS、InDesign、XD、Premiere Pro 等多款软件的插件生态统一到 UXP 上未来新功能、新技术都会优先投在这里。所以不管你现在用不用得上这个方向值得早进场布局早学一天后面迁移成本低一天。1.2 为什么用 Vue 写 UXP 插件UXP 的核心渲染就是 HTML CSS JavaScript所以理论上原生 JS 就能写。但插件面板一旦复杂起来状态同步就成了噩梦。比如面板里一个输入框、一个列表、一个详情区输入框改个值列表和详情都要变原生 DOM 操作写到最后全是 id 和事件回调越写越乱。Vue 最擅长的正是这个响应式数据绑定 组件化。数据一变视图自动更新组件之间通过 props 和事件通信面板 UI 的复杂度被限制在可控范围内。对比 ReactVue 的模板语法更接近传统 HTML写起来直观对从 Web 转到插件开发的人尤其友好。对比旧时代的 ExtendScript那个 ES3 语法的老古董Vue 开发体验完全是天壤之别你可以用现代 ES 语法、用组件化思想、用已有的前端工程化工具链。当然选 Vue 不代表 UXP 对 Vue 有特殊支持也绝对不能把 Vue 项目扔进 UXP 直接跑需要打包转换。UXP 运行环境缺少浏览器里很多东西比如我们没有完整的 BOM、很多 DOM API 是子集所以要靠构建工具把 Vue 组件最终编译成 UXP 能认的标准 JS 和 HTML 文件。1.3 Windows 下的技术栈选型我这次在 Windows 上搭建的完整技术栈如下组件选择理由操作系统Windows 10/11 64位目标平台就是 Windows注意路径别用中文Node.js18 LTS兼容性最好避免新版本与原生模块冲突包管理器npm默认集成第三方插件都兼容开发工具VS Code UXP Developer ToolVS Code 有插件支持UDT 负责加载调试前端框架Vue 2.7稳妥方案 组合式 APIUXP 内核对现代语法支持有限见下文构建工具webpack babel能把 Vue SFC 和 ES 高版本语法降到 UXP 可运行范围宿主应用Adobe Photoshop 24.x 或更新版本越新UXP API 支持越完整这套组合是目前社区里案例最多、参考资料最全的路径。只要你照着走大概率不会卡在“没有人这么干过”的荒原上。开发环境的核心是 UXP Developer Tool下面我统一叫 UDT它负责加载插件、看日志、启动宿主程序是整个链路里最关键的枢纽。2. Windows 环境准备先把工具链装齐2.1 Node.js 与 npm版本别贪新很多环境搭建的坑都出在 Node 版本太新导致依赖安装失败。UXP 插件开发用到的很多模板项目还挂着 node-sass、旧版 webpack 这类依赖如果直接上 Node 20/22大概率会编译失败报错信息又长又难懂什么“gyp ERR”“MSBuild failed”都会冒出来。建议统一用 Node 18 LTS这是目前兼容面最大的版本。如果电脑上已经有别的 Node 版本推荐先装 nvm-windows 来做版本切换命令行几秒钟切到 18干完活再切回去互不影响。安装完以后执行node -v npm -v能看到版本号输出就算过关。接下来可以顺手把 npm 镜像源切一下国内网络环境能省不少时间npm config set registry https://registry.npmmirror.com这一步不是必须但实测能明显提升npm install的速度和成功率。2.2 UXP Developer Tool 的安装与首次设置UDT 是 Adobe 官方出的桌面调试工具Windows 版可以直接从 Adobe 官网下载安装。安装包不大装完以后启动界面比较简洁左侧是插件列表右侧是日志面板。首次打开建议先确认 Creative Cloud 账号已登录并且你把目标宿主软件比如 Photoshop也装好了这样 UDT 在拉起宿主应用时不会出现认证不一致的问题。使用 UDT 最关键的操作是 Add Plugin。点击后选择你的项目目录UDT 会去读取该目录下的 manifest.json把它识别为一个可加载插件。注意这里有个小坑项目里如果存在src和dist两份 manifest你要区分清楚该加载哪个开发调试阶段一般加载包含打包产物的那个 manifest避免改完代码还要手动复制文件。UDT 还会帮你在 Photoshop 菜单里创建一个“插件”入口点击入口可以直接启动插件面板。调试过程中右侧日志面板会输出console.log的内容这是插件开发最主要的调试手段要习惯有事没事先打日志。2.3 确认 Photoshop 版本与 UXP 兼容性不是所有 Photoshop 版本都适合做 UXP 开发。UXP 支持从 Photoshop 22.0 开始引入但真正稳定好用是从 22.4 之后才开始的建议直接装 Photoshop 2023 或 2024也就是 24.x / 25.x版本API 更全遇到新特性的支持也更及时。另外如果你以后想让插件同时跑 InDesign同一套代码是可以复用的只需要在 manifest 的 host 里多声明一个应用这一点后面会讲。在 Windows 上检查 PS 版本很简单打开 Photoshop菜单栏点“帮助 → 关于 Photoshop”或者直接看安装目录的可执行文件属性都能看到具体版本号。只要主版本号大于等于 22就不用担心 UXP 兼容性当然老版本宿主暴露的 UXP API 可能会少一些代码里用到新特性时建议做能力检测。3. Vue 项目初始化与 UXP 模板集成3.1 基于 uxp-vue-template 初始化项目官方维护了一批 UXP 模板其中uxp-vue-template就是为 Vue 开发准备的。直接命令行操作git clone https://github.com/Adobe-UXP/uxp-vue-template.git my-uxp-plugin cd my-uxp-plugin npm installnpm install过程如果没报错说明环境基本通了。这个模板内部已经配置好了 webpack、babel、vue-loader 等一系列工程化依赖src 目录就是你的 Vue 源码dist 目录是构建产物。比起自己从零搓 webpack 配置用模板能省掉大量试错时间。第一次 clone 完以后建议先不改任何代码直接npm run build看能否顺利产出 dist 目录。这一步如果走通后面所有问题都只存在于你的业务代码里如果连这里都报错多半是 Node 版本问题切到 18 再试。有一点要提醒模板项目里用了 Vue 2.7原因是 UXP 内核对 Vue 3 依赖的 Proxy 等特性支持存在兼容性风险白屏排查起来非常头大。二点七版本同时提供了组合式 API 支持写代码时可以享受到现代 Vue 的语法糖但运行时代价更小这个取舍我认为很划算。3.2 逐行拆解 manifest.jsonmanifest.json 是 UXP 插件的地基UDT 靠它识别插件宿主应用靠它决定插件能不能运行。下面是基于模板整理出的最小可用配置{ manifestVersion: 4, id: com.example.vueplugin, name: VuePlugin, version: 1.0.0, main: dist/index.html, host: [ { app: PS, minVersion: 22.4.0 } ], requiredPermissions: { localFileSystem: fullAccess }, icons: [ { width: 48, height: 48, path: icons/icon.png, scale: [1] } ] }逐字段解释一下关键项manifestVersion当前 UXP manifest 的版本号4 是近几年通用值别自己乱改。id插件唯一标识建议用反向域名风格比如公司域名 项目名避免和别人冲突。main插件入口页面路径这里必须是指向构建产物 dist 下的 html不是源码。host插件要跑在哪个宿主应用里。app填PS代表 Photoshop如果还想支持 InDesign就追加一个{ app: ID, minVersion: 17.0.0 }。requiredPermissions权限声明。localFileSystem 控制本地文件读写默认不声明的话很多文件能力不可用我直接给了 fullAccess 以方便调试。icons插件在 Photoshop 菜单/面板里显示的图标。没有图标时插件大概率还能加载但会报警告建议还是准备一个简单 png 放着。配置完成后每次修改name或id都要重新加载插件才生效UDT 里点一下 reload 就好。3.3 构建配置Vue 在 UXP 里最卡人的一环UXP 运行环境和浏览器最大区别在于它没有地址栏、没有 iframe、没有 localStorage 这些日常依赖而且执行的 JavaScript 语法不能太超前。Vite 默认构建目标面向现代浏览器产出代码对 UXP 来说往往太激进我用下来最容易导致白屏。所以模板里用的还是 webpack babel重点就是做语法的“降级兼容”。webpack 配置里最核心的几项如下const path require(path); const HtmlWebpackPlugin require(html-webpack-plugin); const { VueLoaderPlugin } require(vue-loader); module.exports { mode: development, entry: ./src/main.js, output: { path: path.resolve(__dirname, dist), filename: index.js, clean: true }, target: [web, es2018], module: { rules: [ { test: /\.vue$/, loader: vue-loader }, { test: /\.js$/, use: babel-loader, exclude: /node_modules/ }, { test: /\.css$/, use: [style-loader, css-loader] } ] }, plugins: [ new VueLoaderPlugin(), new HtmlWebpackPlugin({ template: ./src/index.html }) ], optimization: { minimize: false } };这里几个关键点值得多花点心思理解target 设成 es2018 而不是 es5。早期很多方案让 Babel 把代码降到 ES5结果 Vue 的响应式系统在某些旧语法模式下反而出现问题而且代码体积膨胀明显。es2018 对当前 UXP 内核是够用的语法新一点调试也舒服。关掉代码压缩minimize: false。压缩本身一般没问题但压缩后的报错信息会变得完全不可读对初期调试就是灾难。等到功能稳定、准备发正式包时再开压缩也不迟。polyfill 不要贪多。UXP 环境确实缺一些浏览器 API但你不需要把整个 core-js 全量打进来太大且可能引入更奇怪的兼容故障。遇到具体报错再按需补比如缺Promise、缺Object.assign就只加那一个 polyfill。如果你确实想试 Vue 3也不是完全不行但建好项目后先做一个最小 App 跑一遍确认没有白屏或 Proxy 相关报错再往里面填业务代码。省得写了几千行业务代码后才发现底层运行有问题回头改工程量很大。4. 程序试运行从代码到 Photoshop 面板4.1 构建产物与 UDT 加载路径代码写完后先执行npm run build确认 dist 目录下生成了index.html和index.js。如果模板还生成了一份manifest.json复制到 dist 目录后面加载就选 dist如果没有就需要手动确保 UDT 加载的是包含了新 main 路径的根 manifest。打开 UDT点击 Add Plugin把项目 dist 目录或根目录取决于 manifest 放置位置加载进来。列表里出现插件名称后点击右侧的 Load 按钮。正常情况下 UDT 会自动拉起 Photoshop或者在你手动打开 Photoshop 后自动给它注入插件。我遇到一个高频误区是加载源码目录而不是构建目录然后看到 PS 里没反应。原因很简单UXP 不认识.vue文件它只认构建后的dist/index.html和dist/index.js。所以每次改完代码先npm run build再在 UDT 点 Reload这个顺序固定下来能减少很多“改了没反应”的困惑。4.2 在 Photoshop 中验证插件与调用 UXP API插件正确加载后Photoshop 顶栏会出现“插件”菜单找到你插件的名字点击即可打开面板。如果是面板类型插件通常会自动停靠在右侧面板区也可以拖出来变成浮动窗口。这一步我们先不写复杂逻辑只验证 Vue 能正常渲染并且能调用 UXP 提供的原生能力。写一段小测试代码在 Vue 组件里放一个按钮点击时读取本地某个文件const fs require(uxp).storage.localFileSystem; async function pickFile() { const file await fs.getFileForOpening({ types: [png] }); if (file) { console.log(选中的文件:, file.name); } }模板里按钮绑定这个函数点击后就会触发 Photoshop 自身的文件选择对话框选中文件后日志打印文件名。这个测试的意义在于它同时验证了 Vue 事件绑定、UXP API 调用、权限配置、日志通道四条链路是否全部正常。如果文件选择对话框能弹出来说明 manifest 里的 localFileSystem 权限生效了如果点击无反应首先看 UDT 日志面板有没有权限报错其次把按钮事件改成直接console.log(click)确认 Vue 事件绑定本身没问题。4.3 调试技巧console.log 与断点UXP 插件调试主要靠 UDT 的日志面板console.log的输出会出现在那里浏览器的 DevTools 在这里没有对应物。所以开发习惯上要主动多打日志尤其在进入 UXP API 调用前后打上边界日志能快速定位问题是出在渲染层还是原生层。断点调试也不是不行UDT 支持启动调试会话在 VS Code 里用 Debugger for UXP 插件可以附加到插件进程设置断点、单步执行都支持。但我个人经验是初期模板验证阶段日志调试已经够用等业务逻辑复杂到日志刷屏时再上断点免得浪费精力。还有一个底层认知要建立UXP 宿主里没有process对象也没有 Node 环境变量。如果你在模板里直接写process.env.NODE_ENV这种代码构建时 webpack 会尝试帮你定义但若在运行时直接访问process就崩了。最好的方式是让 webpack 的 DefinePlugin 来做环境注入业务代码里避免直接依赖 Node 风格全局对象。5. 常见问题与避坑5.1 高频报错原因与解决方案做 UXP 开发很多问题不是代码逻辑问题而是环境链路问题。把高频问题整理成速查表遇到直接对照排查现象常见原因解决方案插件面板白屏控制台无任何输出构建产物语法超出 UXP 内核支持范围检查 webpack target 是否过高改回 es2018Vue 3 可退回 Vue 2.7 验证UDT 报 “Unsupported manifest version”manifestVersion 写错或模板太老改成 4并核对字段名称Photoshop 菜单里找不到插件main 路径指向源码或不存在重新构建 dist确认 manifest 的 main 指向 dist/index.html点击按钮没有任何反应事件未绑定或 UXP API 抛异常按钮事件里先打 console.log确认 Vue 正常再看日志面板的报错详情本地文件读写失败requiredPermissions 未声明 localFileSystem补上requiredPermissions: {localFileSystem: fullAccess}npm install 报 node-sass 编译错误Node 版本过高切换 Node 18 LTS 后重新安装依赖修改代码后 PS 里看不到变化没有重新构建或没有 reload先 npm run build再 UDT 里点 Reload这张表基本覆盖了新手期的 90% 问题。还有一个经常被忽略的细节Windows 下项目目录路径里如果有中文或空格webpack 构建偶尔会出现诡异的路径相关报错把项目放在纯英文路径下比如D:\dev\my-plugin能规避一大票问题。5.2 Windows 特有的一些坑Windows 环境和 macOS 还有差别我自己踩过几个比较典型的。第一个是 PowerShell 执行策略。某些默认配置下运行 npm 脚本会提示“无法加载文件因为在此系统上禁止运行脚本”。处理方法是用管理员身份打开 PowerShell执行一次Set-ExecutionPolicy RemoteSigned然后重新运行 npm。第二个是安全软件拦截。UDT 加载插件时本机调试通信有时候会被防火墙或杀毒软件误判为异常行为表现是宿主应用一直拉不起来或者插件面板加载到一半卡住。处理方式是先把 UDT 相关目录加入防火墙/白名单确保本地回环通信放行。第三个是杀毒软件对 node-sass 这类原生模块的实时扫描导致编译极慢甚至半途失败。可以把 node_modules 目录或项目目录加入实时防护排除名单能明显提速。这些不是 UXP 特有的但 Windows 下开发任何带原生依赖的项目都会遇到提前处理省心很多。5.3 关于后续功能的扩展建议环境跑通、第一个 Vue 组件能显示在 Photoshop 里接下来你会面临一个幸福的烦恼功能边界在哪里我个人经验是UXP 插件不要试图承担太重的前端架构。Vue Router 在 UXP 里意义不大没有 URL、没有历史记录直接用 Vue 的v-if或动态组件切换面板状态就够了。状态管理方面Pinia 或 Vuex 可以用但除非插件逻辑真的复杂到多模块共享状态否则一个简单的 reactive 对象就够用。UI 组件库尽量走轻量路线Adobe 官方也提供过 Spectrum 风格组件但把 Element Plus 这类重库塞进 UXP 往往会出现样式错乱因为 UXP 对 CSS 的支持也是子集很多浏览器特性没有。另外建议尽早把构建脚本分离成开发版和生产版开发版不压缩、保留完整日志、加载更快生产版压缩代码、去掉调试输出、图标完整打包。Adobe 对正式发布的 UXP 插件有审核要求manifest 里的权限声明也要再次收紧能不开 localFileSystem 就不开遵循最小权限原则。根据我个人踩过几次坑之后的体会UXP 开发环境的搭建本身并不难难的是改变在浏览器里写前端时留下的那些无意识依赖。一旦习惯在受限的宿主环境里开发你会发现它比想象中稳定Vue 带来的开发效率也完全能延续到 Adobe 生态里。环境这套东西搭好一次以后每次开新插件项目都只是几分钟的事真正拉开差距的还是对 UXP API 边界的理解和对宿主应用业务逻辑的掌握。
Windows下搭建Vue + UXP的Photoshop插件开发环境完整指南
做 Adobe 生态的插件开发早几年绕不开 CEP最近两年风向明显变了Adobe 把新能力都往 UXP 上推。我刚接触 UXP 时第一反应是“这不就是换个壳的网页开发吗”真正在 Windows 上把环境搭起来、用 Vue 把面板跑起来才发现里面的门道比想象中多。Adobe Photoshop 的插件开发从 CEP 过渡到 UXP本质是从“旧浏览器 Node 环境”转向“受限 Chromium 沙箱”这个转变对前端开发者太友好了因为技术栈终于可以现代化了但踩坑方式也变了。这篇文章我会按实际开发顺序完整记录在 Windows 环境下怎么搭建一套基于 Vue 的 UXP 插件开发环境从 Node 版本选择、UDT 工具安装、Vue 项目初始化、manifest 配置到构建产物加载进 Photoshop 里真正运行起来最后把调试经验和常见报错一并整理出来。如果你之前只写过普通 Web 前端想试试 Adobe 插件开发或者已经写过 CEP 插件想迁移到 UXP这篇应该能帮你少走不少弯路。1. 项目背景与整体思路1.1 UXP 不是 CEP 换个马甲先把这个事情说清楚UXPUnified Extensibility Platform统一可扩展平台和 CEPCommon Extensibility Platform是两代完全不同的插件架构不是简单升级。CEP 基于老版 Chromium嵌入 Node.js 作为后端插件可以直接操作本地文件、启动子进程能力大得离谱但也正因为能力太强插件安全审查、崩溃隔离都很难做。UXP 的设计思路做了个大转向渲染层仍然是 Chromium 内核但运行环境变成沙箱化的没有 Node.js没有自由的本地文件访问所有能力都要通过 Adobe 暴露的 UXP API 来调用。用生活里的话说CEP 像把租客房卡直接办成了万能钥匙UXP 则是物业发的访客门禁卡能进哪些楼层、哪些房间都由物业后台控制。这个设计对用户更安全对开发者来说是约束但换来的是更现代、更统一的开发体系。Adobe 的目标是把 PS、InDesign、XD、Premiere Pro 等多款软件的插件生态统一到 UXP 上未来新功能、新技术都会优先投在这里。所以不管你现在用不用得上这个方向值得早进场布局早学一天后面迁移成本低一天。1.2 为什么用 Vue 写 UXP 插件UXP 的核心渲染就是 HTML CSS JavaScript所以理论上原生 JS 就能写。但插件面板一旦复杂起来状态同步就成了噩梦。比如面板里一个输入框、一个列表、一个详情区输入框改个值列表和详情都要变原生 DOM 操作写到最后全是 id 和事件回调越写越乱。Vue 最擅长的正是这个响应式数据绑定 组件化。数据一变视图自动更新组件之间通过 props 和事件通信面板 UI 的复杂度被限制在可控范围内。对比 ReactVue 的模板语法更接近传统 HTML写起来直观对从 Web 转到插件开发的人尤其友好。对比旧时代的 ExtendScript那个 ES3 语法的老古董Vue 开发体验完全是天壤之别你可以用现代 ES 语法、用组件化思想、用已有的前端工程化工具链。当然选 Vue 不代表 UXP 对 Vue 有特殊支持也绝对不能把 Vue 项目扔进 UXP 直接跑需要打包转换。UXP 运行环境缺少浏览器里很多东西比如我们没有完整的 BOM、很多 DOM API 是子集所以要靠构建工具把 Vue 组件最终编译成 UXP 能认的标准 JS 和 HTML 文件。1.3 Windows 下的技术栈选型我这次在 Windows 上搭建的完整技术栈如下组件选择理由操作系统Windows 10/11 64位目标平台就是 Windows注意路径别用中文Node.js18 LTS兼容性最好避免新版本与原生模块冲突包管理器npm默认集成第三方插件都兼容开发工具VS Code UXP Developer ToolVS Code 有插件支持UDT 负责加载调试前端框架Vue 2.7稳妥方案 组合式 APIUXP 内核对现代语法支持有限见下文构建工具webpack babel能把 Vue SFC 和 ES 高版本语法降到 UXP 可运行范围宿主应用Adobe Photoshop 24.x 或更新版本越新UXP API 支持越完整这套组合是目前社区里案例最多、参考资料最全的路径。只要你照着走大概率不会卡在“没有人这么干过”的荒原上。开发环境的核心是 UXP Developer Tool下面我统一叫 UDT它负责加载插件、看日志、启动宿主程序是整个链路里最关键的枢纽。2. Windows 环境准备先把工具链装齐2.1 Node.js 与 npm版本别贪新很多环境搭建的坑都出在 Node 版本太新导致依赖安装失败。UXP 插件开发用到的很多模板项目还挂着 node-sass、旧版 webpack 这类依赖如果直接上 Node 20/22大概率会编译失败报错信息又长又难懂什么“gyp ERR”“MSBuild failed”都会冒出来。建议统一用 Node 18 LTS这是目前兼容面最大的版本。如果电脑上已经有别的 Node 版本推荐先装 nvm-windows 来做版本切换命令行几秒钟切到 18干完活再切回去互不影响。安装完以后执行node -v npm -v能看到版本号输出就算过关。接下来可以顺手把 npm 镜像源切一下国内网络环境能省不少时间npm config set registry https://registry.npmmirror.com这一步不是必须但实测能明显提升npm install的速度和成功率。2.2 UXP Developer Tool 的安装与首次设置UDT 是 Adobe 官方出的桌面调试工具Windows 版可以直接从 Adobe 官网下载安装。安装包不大装完以后启动界面比较简洁左侧是插件列表右侧是日志面板。首次打开建议先确认 Creative Cloud 账号已登录并且你把目标宿主软件比如 Photoshop也装好了这样 UDT 在拉起宿主应用时不会出现认证不一致的问题。使用 UDT 最关键的操作是 Add Plugin。点击后选择你的项目目录UDT 会去读取该目录下的 manifest.json把它识别为一个可加载插件。注意这里有个小坑项目里如果存在src和dist两份 manifest你要区分清楚该加载哪个开发调试阶段一般加载包含打包产物的那个 manifest避免改完代码还要手动复制文件。UDT 还会帮你在 Photoshop 菜单里创建一个“插件”入口点击入口可以直接启动插件面板。调试过程中右侧日志面板会输出console.log的内容这是插件开发最主要的调试手段要习惯有事没事先打日志。2.3 确认 Photoshop 版本与 UXP 兼容性不是所有 Photoshop 版本都适合做 UXP 开发。UXP 支持从 Photoshop 22.0 开始引入但真正稳定好用是从 22.4 之后才开始的建议直接装 Photoshop 2023 或 2024也就是 24.x / 25.x版本API 更全遇到新特性的支持也更及时。另外如果你以后想让插件同时跑 InDesign同一套代码是可以复用的只需要在 manifest 的 host 里多声明一个应用这一点后面会讲。在 Windows 上检查 PS 版本很简单打开 Photoshop菜单栏点“帮助 → 关于 Photoshop”或者直接看安装目录的可执行文件属性都能看到具体版本号。只要主版本号大于等于 22就不用担心 UXP 兼容性当然老版本宿主暴露的 UXP API 可能会少一些代码里用到新特性时建议做能力检测。3. Vue 项目初始化与 UXP 模板集成3.1 基于 uxp-vue-template 初始化项目官方维护了一批 UXP 模板其中uxp-vue-template就是为 Vue 开发准备的。直接命令行操作git clone https://github.com/Adobe-UXP/uxp-vue-template.git my-uxp-plugin cd my-uxp-plugin npm installnpm install过程如果没报错说明环境基本通了。这个模板内部已经配置好了 webpack、babel、vue-loader 等一系列工程化依赖src 目录就是你的 Vue 源码dist 目录是构建产物。比起自己从零搓 webpack 配置用模板能省掉大量试错时间。第一次 clone 完以后建议先不改任何代码直接npm run build看能否顺利产出 dist 目录。这一步如果走通后面所有问题都只存在于你的业务代码里如果连这里都报错多半是 Node 版本问题切到 18 再试。有一点要提醒模板项目里用了 Vue 2.7原因是 UXP 内核对 Vue 3 依赖的 Proxy 等特性支持存在兼容性风险白屏排查起来非常头大。二点七版本同时提供了组合式 API 支持写代码时可以享受到现代 Vue 的语法糖但运行时代价更小这个取舍我认为很划算。3.2 逐行拆解 manifest.jsonmanifest.json 是 UXP 插件的地基UDT 靠它识别插件宿主应用靠它决定插件能不能运行。下面是基于模板整理出的最小可用配置{ manifestVersion: 4, id: com.example.vueplugin, name: VuePlugin, version: 1.0.0, main: dist/index.html, host: [ { app: PS, minVersion: 22.4.0 } ], requiredPermissions: { localFileSystem: fullAccess }, icons: [ { width: 48, height: 48, path: icons/icon.png, scale: [1] } ] }逐字段解释一下关键项manifestVersion当前 UXP manifest 的版本号4 是近几年通用值别自己乱改。id插件唯一标识建议用反向域名风格比如公司域名 项目名避免和别人冲突。main插件入口页面路径这里必须是指向构建产物 dist 下的 html不是源码。host插件要跑在哪个宿主应用里。app填PS代表 Photoshop如果还想支持 InDesign就追加一个{ app: ID, minVersion: 17.0.0 }。requiredPermissions权限声明。localFileSystem 控制本地文件读写默认不声明的话很多文件能力不可用我直接给了 fullAccess 以方便调试。icons插件在 Photoshop 菜单/面板里显示的图标。没有图标时插件大概率还能加载但会报警告建议还是准备一个简单 png 放着。配置完成后每次修改name或id都要重新加载插件才生效UDT 里点一下 reload 就好。3.3 构建配置Vue 在 UXP 里最卡人的一环UXP 运行环境和浏览器最大区别在于它没有地址栏、没有 iframe、没有 localStorage 这些日常依赖而且执行的 JavaScript 语法不能太超前。Vite 默认构建目标面向现代浏览器产出代码对 UXP 来说往往太激进我用下来最容易导致白屏。所以模板里用的还是 webpack babel重点就是做语法的“降级兼容”。webpack 配置里最核心的几项如下const path require(path); const HtmlWebpackPlugin require(html-webpack-plugin); const { VueLoaderPlugin } require(vue-loader); module.exports { mode: development, entry: ./src/main.js, output: { path: path.resolve(__dirname, dist), filename: index.js, clean: true }, target: [web, es2018], module: { rules: [ { test: /\.vue$/, loader: vue-loader }, { test: /\.js$/, use: babel-loader, exclude: /node_modules/ }, { test: /\.css$/, use: [style-loader, css-loader] } ] }, plugins: [ new VueLoaderPlugin(), new HtmlWebpackPlugin({ template: ./src/index.html }) ], optimization: { minimize: false } };这里几个关键点值得多花点心思理解target 设成 es2018 而不是 es5。早期很多方案让 Babel 把代码降到 ES5结果 Vue 的响应式系统在某些旧语法模式下反而出现问题而且代码体积膨胀明显。es2018 对当前 UXP 内核是够用的语法新一点调试也舒服。关掉代码压缩minimize: false。压缩本身一般没问题但压缩后的报错信息会变得完全不可读对初期调试就是灾难。等到功能稳定、准备发正式包时再开压缩也不迟。polyfill 不要贪多。UXP 环境确实缺一些浏览器 API但你不需要把整个 core-js 全量打进来太大且可能引入更奇怪的兼容故障。遇到具体报错再按需补比如缺Promise、缺Object.assign就只加那一个 polyfill。如果你确实想试 Vue 3也不是完全不行但建好项目后先做一个最小 App 跑一遍确认没有白屏或 Proxy 相关报错再往里面填业务代码。省得写了几千行业务代码后才发现底层运行有问题回头改工程量很大。4. 程序试运行从代码到 Photoshop 面板4.1 构建产物与 UDT 加载路径代码写完后先执行npm run build确认 dist 目录下生成了index.html和index.js。如果模板还生成了一份manifest.json复制到 dist 目录后面加载就选 dist如果没有就需要手动确保 UDT 加载的是包含了新 main 路径的根 manifest。打开 UDT点击 Add Plugin把项目 dist 目录或根目录取决于 manifest 放置位置加载进来。列表里出现插件名称后点击右侧的 Load 按钮。正常情况下 UDT 会自动拉起 Photoshop或者在你手动打开 Photoshop 后自动给它注入插件。我遇到一个高频误区是加载源码目录而不是构建目录然后看到 PS 里没反应。原因很简单UXP 不认识.vue文件它只认构建后的dist/index.html和dist/index.js。所以每次改完代码先npm run build再在 UDT 点 Reload这个顺序固定下来能减少很多“改了没反应”的困惑。4.2 在 Photoshop 中验证插件与调用 UXP API插件正确加载后Photoshop 顶栏会出现“插件”菜单找到你插件的名字点击即可打开面板。如果是面板类型插件通常会自动停靠在右侧面板区也可以拖出来变成浮动窗口。这一步我们先不写复杂逻辑只验证 Vue 能正常渲染并且能调用 UXP 提供的原生能力。写一段小测试代码在 Vue 组件里放一个按钮点击时读取本地某个文件const fs require(uxp).storage.localFileSystem; async function pickFile() { const file await fs.getFileForOpening({ types: [png] }); if (file) { console.log(选中的文件:, file.name); } }模板里按钮绑定这个函数点击后就会触发 Photoshop 自身的文件选择对话框选中文件后日志打印文件名。这个测试的意义在于它同时验证了 Vue 事件绑定、UXP API 调用、权限配置、日志通道四条链路是否全部正常。如果文件选择对话框能弹出来说明 manifest 里的 localFileSystem 权限生效了如果点击无反应首先看 UDT 日志面板有没有权限报错其次把按钮事件改成直接console.log(click)确认 Vue 事件绑定本身没问题。4.3 调试技巧console.log 与断点UXP 插件调试主要靠 UDT 的日志面板console.log的输出会出现在那里浏览器的 DevTools 在这里没有对应物。所以开发习惯上要主动多打日志尤其在进入 UXP API 调用前后打上边界日志能快速定位问题是出在渲染层还是原生层。断点调试也不是不行UDT 支持启动调试会话在 VS Code 里用 Debugger for UXP 插件可以附加到插件进程设置断点、单步执行都支持。但我个人经验是初期模板验证阶段日志调试已经够用等业务逻辑复杂到日志刷屏时再上断点免得浪费精力。还有一个底层认知要建立UXP 宿主里没有process对象也没有 Node 环境变量。如果你在模板里直接写process.env.NODE_ENV这种代码构建时 webpack 会尝试帮你定义但若在运行时直接访问process就崩了。最好的方式是让 webpack 的 DefinePlugin 来做环境注入业务代码里避免直接依赖 Node 风格全局对象。5. 常见问题与避坑5.1 高频报错原因与解决方案做 UXP 开发很多问题不是代码逻辑问题而是环境链路问题。把高频问题整理成速查表遇到直接对照排查现象常见原因解决方案插件面板白屏控制台无任何输出构建产物语法超出 UXP 内核支持范围检查 webpack target 是否过高改回 es2018Vue 3 可退回 Vue 2.7 验证UDT 报 “Unsupported manifest version”manifestVersion 写错或模板太老改成 4并核对字段名称Photoshop 菜单里找不到插件main 路径指向源码或不存在重新构建 dist确认 manifest 的 main 指向 dist/index.html点击按钮没有任何反应事件未绑定或 UXP API 抛异常按钮事件里先打 console.log确认 Vue 正常再看日志面板的报错详情本地文件读写失败requiredPermissions 未声明 localFileSystem补上requiredPermissions: {localFileSystem: fullAccess}npm install 报 node-sass 编译错误Node 版本过高切换 Node 18 LTS 后重新安装依赖修改代码后 PS 里看不到变化没有重新构建或没有 reload先 npm run build再 UDT 里点 Reload这张表基本覆盖了新手期的 90% 问题。还有一个经常被忽略的细节Windows 下项目目录路径里如果有中文或空格webpack 构建偶尔会出现诡异的路径相关报错把项目放在纯英文路径下比如D:\dev\my-plugin能规避一大票问题。5.2 Windows 特有的一些坑Windows 环境和 macOS 还有差别我自己踩过几个比较典型的。第一个是 PowerShell 执行策略。某些默认配置下运行 npm 脚本会提示“无法加载文件因为在此系统上禁止运行脚本”。处理方法是用管理员身份打开 PowerShell执行一次Set-ExecutionPolicy RemoteSigned然后重新运行 npm。第二个是安全软件拦截。UDT 加载插件时本机调试通信有时候会被防火墙或杀毒软件误判为异常行为表现是宿主应用一直拉不起来或者插件面板加载到一半卡住。处理方式是先把 UDT 相关目录加入防火墙/白名单确保本地回环通信放行。第三个是杀毒软件对 node-sass 这类原生模块的实时扫描导致编译极慢甚至半途失败。可以把 node_modules 目录或项目目录加入实时防护排除名单能明显提速。这些不是 UXP 特有的但 Windows 下开发任何带原生依赖的项目都会遇到提前处理省心很多。5.3 关于后续功能的扩展建议环境跑通、第一个 Vue 组件能显示在 Photoshop 里接下来你会面临一个幸福的烦恼功能边界在哪里我个人经验是UXP 插件不要试图承担太重的前端架构。Vue Router 在 UXP 里意义不大没有 URL、没有历史记录直接用 Vue 的v-if或动态组件切换面板状态就够了。状态管理方面Pinia 或 Vuex 可以用但除非插件逻辑真的复杂到多模块共享状态否则一个简单的 reactive 对象就够用。UI 组件库尽量走轻量路线Adobe 官方也提供过 Spectrum 风格组件但把 Element Plus 这类重库塞进 UXP 往往会出现样式错乱因为 UXP 对 CSS 的支持也是子集很多浏览器特性没有。另外建议尽早把构建脚本分离成开发版和生产版开发版不压缩、保留完整日志、加载更快生产版压缩代码、去掉调试输出、图标完整打包。Adobe 对正式发布的 UXP 插件有审核要求manifest 里的权限声明也要再次收紧能不开 localFileSystem 就不开遵循最小权限原则。根据我个人踩过几次坑之后的体会UXP 开发环境的搭建本身并不难难的是改变在浏览器里写前端时留下的那些无意识依赖。一旦习惯在受限的宿主环境里开发你会发现它比想象中稳定Vue 带来的开发效率也完全能延续到 Adobe 生态里。环境这套东西搭好一次以后每次开新插件项目都只是几分钟的事真正拉开差距的还是对 UXP API 边界的理解和对宿主应用业务逻辑的掌握。
