Strapi Cloud 插件源码解析：从管理面板一键部署到 CLI 发布链路

本文基于 Strapi 官方仓库中的 @strapi/plugin-cloud 插件（源码位于 packages/plugins/cloud），系统讲解这个"部署助手"插件的定位、页面结构、两种部署方式（Strapi Cloud 控制台与 CLI）的完整实现细节，以及它在管理后台中的注册机制与构建打包方式。读完后，你不仅能在 Strapi 管理面板中正确使用该插件完成部署操作，还能看懂它"仅在非生产环境显示"、"按语言加载翻译文件"等关键设计背后的源码逻辑。

插件定位：把"部署"这件事搬进管理面板

按照插件的 README 所述，@strapi/plugin-cloud 是一个帮助开发者将 Strapi 项目部署到 Strapi Cloud 的插件，它提供 UI 让开发者选择部署方式，并"在几次点击内"启动项目部署。其 README 列出的核心特性包括：

• 支持在 Strapi Cloud 控制台（推荐）与 CLI 两种部署方式之间切换；
• 内置操作指引，并可快速跳转到官方文档。

从 package.json 可以确认该插件的关键元信息：

字段	值	说明
name	@strapi/plugin-cloud	npm 包名
version	5.52.2	与 Strapi 5 主线同版本
strapi.name	strapi-cloud	Strapi 插件体系中的插件标识名
strapi.kind	plugin	声明为插件类型
strapi.displayName	Strapi Cloud	管理面板中展示的名称
engines.node	>=20.0.0 <=26.x.x	适用的 Node 版本范围

值得注意的是，exports 字段只暴露了 ./strapi-admin 一个入口（源码指向 admin/src/index.ts），说明这是一个纯前端（Admin 端）插件：它没有 server 侧代码，不参与运行时路由，只负责在管理面板中渲染部署指引页面。

插件入口：菜单注册与翻译加载

插件的入口是 admin/src/index.ts，它遵循 Strapi Admin 插件的标准生命周期，包含 register 和 registerTrads 两个方法。

注册菜单与插件

register(app) 中做了两件事：

1. 添加侧边栏菜单项：通过 app.addMenuLink 在管理面板侧边栏注入一个名为 "Deploy"（对应翻译键 ${pluginId}.Plugin.name）的菜单项，使用 @strapi/icons 中的 Cloud 图标，路由指向 plugins/cloud，页面组件通过动态 import('./pages/App') 懒加载；
2. 注册插件：app.registerPlugin 声明 id: 'cloud'（来自 pluginId.ts 中的 export const pluginId = 'cloud'）、name: 'Deploy'，并把 Initializer 组件交给框架。

Initializer 的实现很典型：它是一个返回 null 的空组件，通过 useEffect + useRef 在挂载时调用框架传入的 setPlugin(pluginId)，通知管理面板"cloud 插件已就绪"，从而驱动侧边栏等 UI 的更新逻辑。

按需加载翻译文件

registerTrads({ locales }) 展示了 Strapi 插件 i18n 的标准做法：框架会告知管理面板当前启用的语言列表，插件对每个 locale 动态 import(./translations/${locale}.json)，并用 prefixPluginTranslations 给所有翻译键统一加上 cloud. 前缀，避免与内置翻译键冲突；若某语言文件加载失败则静默回退为空对象（回退到代码中的 defaultMessage）。当前该插件在 admin/src/translations 下提供了 13 种语言的翻译文件（en.json、fr、es、de 体系外的 cs/it/ja/ko/nl/pl/ru/sk/tr/uk 等）。

另外可以顺带确认一处工程化细节：Strapi 核心包在 aliases.ts 中将 @strapi/plugin-cloud/strapi-admin 别名直接指向 ./packages/plugins/cloud/admin/src，因此仓库内其他包或开发环境下引用该插件时走的是源码而非 dist 产物。

页面骨架：一个"仅非生产环境可用"的页面

插件的路由骨架在 pages/App.tsx 中，其中有一个值得关注的设计：

const currentEnvironment = useAppInfo('CloudApp', (state) => state.currentEnvironment);

if (currentEnvironment === 'production') {
  return <Navigate to="/" replace />;
}

即当 Strapi 以生产环境（NODE_ENV=production）运行时，访问 plugins/cloud 路由会被重定向回首页，部署指引页面直接不可用。从源码结构看，这是有意为之的边界：该页面只服务于"把本地项目部署上云"这一开发期场景，生产实例本身就是已部署产物，不应再展示部署入口。路由本身只注册了 index（首页）与通配符错误页，整个插件只有一个实际页面，这也解释了为什么 rollup.config.mjs 只负责把 admin/src/index.ts 打成一个前端产物。

部署方式一：Strapi Cloud 控制台（推荐）

HomePage 是插件唯一的页面，结构自上而下为：标题（"Deploy with Strapi Cloud"）→ 副标题（强调托管云平台的自动化部署与全球 CDN）→ CloudFeatures 特性清单 → CloudDeploy 部署方式选择器。

CloudFeatures 用带对勾图标的清单展示了 Strapi Cloud 的三大卖点：Global CDN、Push to deploy、Custom domains（对应翻译键 Homepage.features.*），文案全部走 react-intl 的 formatMessage 以保证多语言支持。

核心的方式选择器是 CloudDeploy，它使用 Design System 的 Tabs 组件实现了两个页签：

• Cloud 页签（默认，带 "Recommended" 徽标）：引导用户在 Strapi Cloud 控制台中直接关联 GitHub 或 GitLab 仓库进行部署。页面提供两个跳转出口：主按钮 LinkButton（文案 "Deploy to Strapi Cloud"）与上方的 CloudUpload 图标，均指向 https://cloud.strapi.io/login（带 utm_source=In-Product 等来源参数）；页签底部还有一个 "Having trouble? Check our documentation" 链接，跳转到官方文档的 cloud 部署入门章节。
• CLI 页签：面向希望从命令行部署的开发者，说明文字指出其工作模式是"用命令行把本地项目关联到一个已存在的 Strapi Cloud 项目，然后直接从 CLI 部署变更"，具体命令见下一节。

部署方式二：CLI 部署与命令一键复制

CLI 页签内嵌了 CLIDeployTabs 组件，它按包管理器（Yarn / NPM）两个子页签展示实际要执行的命令，命令定义在组件顶部的常量表中：

const commands: Record<'yarn' | 'npm', { link: string; deploy: string }> = {
  yarn: {
    link: 'yarn strapi link',
    deploy: 'yarn strapi deploy',
  },
  npm: {
    link: 'npm run strapi link',
    deploy: 'npm run strapi deploy',
  },
};

即完整的 CLI 部署链路为两步：

1. strapi link —— 将本地项目链接到 Strapi Cloud 上已存在的项目（Yarn 项目执行 yarn strapi link，npm 项目执行 npm run strapi link）；
2. strapi deploy —— 执行部署（yarn strapi deploy / npm run strapi deploy）。

体验上的细节也值得一提：每条命令右侧配有一个 CopyCommandButton 复制按钮，它复用 @strapi/admin/strapi-admin 导出的 useClipboard 与 useNotification 两个 Hook——点击后把命令写入剪贴板，成功时弹出 "Command copied to clipboard" 的成功通知。这属于"零配置、零依赖"的引导式设计：插件本身不发起任何部署请求，只负责展示正确命令并降低复制成本。

构建与产物结构

从 package.json 的 scripts 看，该插件的构建流程为：

• build:code：通过根目录共享的 rollup 配置 打包前端代码；
• build:types:admin：用 tsc -p admin/tsconfig.build.json --emitDeclarationOnly 单独产出 dist/admin/src/index.d.ts 类型声明，与 exports["./strapi-admin"].types 对应；
• clean：rimraf ./dist；
• develop：strapi-plugin watch，配合 Strapi CLI 的插件监听模式做本地开发；
• test:ts:front：直接以 tsc -p admin/tsconfig.json 做前端类型检查。

files: ["dist/"] 表明发布到 npm 时只携带构建产物；而开发依赖中引入 @strapi/admin 与 @strapi/strapi（均为 5.52.2）则用于类型与本地联调，运行时则通过 peerDependencies 声明对 @strapi/admin ^5.0.0、react ^17 || ^18、react-router-dom ^6.30.3、styled-components ^6 的依赖约束，保证插件可嵌入任意 Strapi 5 管理面板。

小结

@strapi/plugin-cloud 是 Strapi 5 中一个职责边界非常清晰的"轻插件"：没有 server 端逻辑，只有一个管理面板页面，围绕 README 所述的两大特性——选择部署方式与内置文档指引——实现了一个双页签的部署引导 UI（控制台跳转 + CLI 命令复制），并通过 currentEnvironment 守卫保证它不会出现在生产实例中。对二次开发者的参考价值在于：它演示了 Strapi 5 Admin 插件的最小完整形态——package.json 的 strapi 元信息块、register/registerTrads 生命周期、Initializer 的就绪通知、动态翻译加载与前缀隔离，以及 rollup + tsc 声明文件的双轨构建，这些模式可以直接套用到自研管理面板插件上。