企业官网建设流程全解析

做 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 换个马甲

先把这个事情说清楚：UXP（Unified Extensibility Platform，统一可扩展平台）和 CEP（Common 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 的复杂度被限制在可控范围内。对比 React，Vue 的模板语法更接近传统 HTML，写起来直观，对从 Web 转到插件开发的人尤其友好。对比旧时代的 ExtendScript（那个 ES3 语法的老古董），Vue 开发体验完全是天壤之别，你可以用现代 ES 语法、用组件化思想、用已有的前端工程化工具链。

当然，选 Vue 不代表 UXP 对 Vue 有特殊支持，也绝对不能把 Vue 项目扔进 UXP 直接跑，需要打包转换。UXP 运行环境缺少浏览器里很多东西，比如我们没有完整的 BOM、很多 DOM API 是子集，所以要靠构建工具把 Vue 组件最终编译成 UXP 能认的标准 JS 和 HTML 文件。

1.3 Windows 下的技术栈选型

我这次在 Windows 上搭建的完整技术栈如下：

这套组合是目前社区里案例最多、参考资料最全的路径。只要你照着走，大概率不会卡在“没有人这么干过”的荒原上。开发环境的核心是 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 install

npm 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.json

manifest.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 开发，很多问题不是代码逻辑问题，而是环境链路问题。把高频问题整理成速查表，遇到直接对照排查：

这张表基本覆盖了新手期的 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 边界的理解和对宿主应用业务逻辑的掌握。