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

想在Adobe系的软件里写自己的插件，翻来覆去搜出来的教程可能还停留在CEP时代的老路子上。Adobe这些年把插件开发框架从CEP迁到了UXP，生态和工程方式都变了。这篇文章是Windows平台上从零搭建UXP插件开发环境，并用Vue写完第一个插件并成功试运行的完整记录。不敢说覆盖所有坑，但环境搭建、Vue工程接入、宿主API调用、运行调试这条链路，我可以保证是实际跑通过、并且很多细节是百度不到的经验。

适合这几类人看：刚接触Adobe插件开发、想用Vue/React这类现代前端框架干活、或者之前被CEP折磨过想换新方案的朋友。文章不会只贴几个命令就完事，我会把每个关键步骤背后的选择逻辑也讲清楚。

1. 先想明白UXP和CEP的区别，再决定要不要换赛道

1.1 CEP到底差在哪

老一代CEP（Common Extensibility Platform）的做法是在Adobe宿主应用里内嵌一个CEF（Chromium Embedded Framework）浏览器，插件面板本质就是一个网页，开发时可以用很完整的浏览器环境。

听起来很美，但实际用起来问题不少：

资源占用高。每打开一个面板，宿主进程就被拖累，PS、AI这类本身内存大户再叠几个CEF，16G内存都能报警。
宿主兼容性不稳定。不同宿主、不同版本捆绑的CEF版本不一致，经常出现这个版本能跑、换了版本就白屏。
开发调试割裂。CEP插件需要用专门的工具去连调试端口，或者用老旧的模拟环境，整个体验和现代Web开发差着辈分。

我早期做AI插件的时候就吃过这个亏，面板里一个简单的input，在Windows上某个版本突然获取不到焦点，排查一整天发现是CEF内部bug。这种问题基本无解，只能绕。

1.2 UXP给插件开发带来了什么

UXP（Unified Extensibility Platform）是Adobe自己实现的Web运行时，目标是把插件引擎统一成一套。它不依赖完整的浏览器内核，而是内嵌一个精简的运行时，加载速度更快、内存占用更低，同时提供了相对统一的宿主API接口。

UXP带给开发者最直观的变化：

开发语言还是Web那一套：HTML、CSS、JavaScript，上手成本低。
内置模块机制：通过require("photoshop")、require("illustrator")这类内置模块访问宿主能力，不用像CEP那样通过共享内存来回通信，开发体验更像写Node.js。
调试体验接近现代Web：配合UXP Developer Tool能用上Chromium DevTools，console、断点都能用。
工程化友好：因为本质是Web技术，Vue、React、Vite这些前端工具链理论上都能接入。

当然UXP不是万能的，很多底层能力还在快速迭代，某些浏览器API在UXP里并不存在。所以越早动手，越能提前摸清边界。

提示：文章后面的示例我会以Photoshop作为宿主应用来演示。核心流程换到Illustrator、InDesign时基本一致，只有manifest里的宿主标识需要改。

1.3 哪些宿主应用已经支持UXP

目前UXP主要覆盖这些Adobe产品：

宿主应用	关键版本要求	UXP支持程度
Photoshop	22.0及以上	较完善，适合入门
Illustrator	27.0及以上	较完善
InDesign	17.0及以上	可用，界面类功能支持较好
Premiere Pro / After Effects	较新版本	逐步开放
XD	早期UXP试验田	已被官方逐步定调迁移到新方案

我的建议是：如果你是第一次尝试UXP，直接用最新版Photoshop，资料多、API稳定、网上踩坑案例也多。别拿老版本宿主硬试，否则会出现manifest明明没问题却加载失败的情况。

2. 环境准备：三个环节缺一不可

2.1 Node.js：Vue工程的地基

UXP插件本身不需要Node.js，但只要你打算用Vue、Vite这套工程链，Node.js就是必须的。

安装时直接选LTS版本，我用的是18，Vite、Vue 3对这个版本支持得很稳。装完在CMD或PowerShell里确认一下：

node -v npm -v

能正常输出版本号说明Node环境没问题。

我特别提醒一个Windows上的习惯性动作：安装路径不要带中文。很多人默认C盘用户名是中文，后面npm install报各种莫名依赖错误，十有八九和路径编码有关。实在躲不开中文用户目录，就手动把Node安装到一个纯英文路径下。

2.2 UXP Developer Tool：调试和加载的核心

UDT（UXP 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.html

manifest.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 charset="utf-8"> <title>UXP HTML Demo</title> </head> <body> <div id="app"> <h1>原生HTML插件面板</h1> <button id="btnAlert">弹出宿主提示</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 src="vue.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.css

src/main.js是Vue应用的入口：

import { createApp } from "vue"; import App from "./App.vue"; createApp(App).mount("#app");

src/App.vue先写一个最简单的组件，验证Vue能正常渲染：

<template> <div> <h1>Vue 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.js：

import { 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.js

Vue组件里能不能直接require("photoshop")？能，但强烈不建议。

原因有两方面。第一，require是UXP运行时注入的CommonJS能力，Vite构建时遇到这种非标准调用，处理不好会直接构建失败；第二，UI层和宿主API层耦合在一起，后面要支持多个宿主应用、或者要Mock数据做单元测试，会很难受。

我把宿主API单独封装到host-api.js：

exports.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> <h1>Vue UXP 试运行</h1> <p>{{ message }}</p> <button @click="readDocumentName">读取文档名</button> <button @click="hostAlert">调用宿主提示</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 charset="utf-8"> <title>Vue UXP Demo</title> <link rel="stylesheet" href="dist/style.css"> </head> <body> <div id="app"></div> <script src="dist/main.js"></script> </body> </html>

这里和之前的裸插件有个明显区别：<div id="app">不需要任何内容，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调用	按钮点击无反应或报undefined	plugin.js是否执行、globalThis挂载

我每次遇到问题都会按这个表格逐层检查，而不是上来就怀疑Vue配置。

5.2 高概率踩中的报错与根因

这里整理几个最常见的问题，每个都是我实际遇到过的。

问题1：UDT提示“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就是引用路径问题。

问题3：globalThis.hostApi is undefined

先确认plugin.js到底有没有被执行。在plugin.js的create回调里加一行console.log("plugin.js executed")，然后看UDT的日志。如果这条日志都看不到，说明manifest的main字段指向错误，或者插件根本没被重新加载。如果日志看得到但hostApi还是undefined，检查require("./host-api.js")的路径，UXP对相对路径的大小写很敏感。

问题4：Vue构建产物里出现“require is not defined”

这通常是因为你在Vue组件源码里直接用了require("photoshop")，Vite在构建时保留了CommonJS调用，但插件里的执行环境和预期不一致。解决方案就是回到第4章的方案：把宿主API调用全部放host-api.js，UI层绝不直接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章的排查链路一层层拆解，大部分问题都能定位到具体节点。

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