wp-calypso 仓库 apps 目录全解析：独立应用的组织、构建与校验实践

前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载导读apps/是 wp-calypso 这个超大 Monorepo 中专门承载独立可部署产物的目录——这里的每一个子项目都能产出类似二进制的独立构建物被部署到 Calypso 主应用之外的场景例如 WordPress.com 插件、widgets.wp.com域名下的 iframe 应用等。本文围绕 apps/README.md 的核心约定结合 monorepo 文档 与仓库内真实应用的package.json完整讲解 apps 与 packages 的定位差异、手动构建流程、package.json的 ESLint 校验机制以及新增一个 app 的标准路径帮助你准确理解并操作这个目录。apps 目录的定位独立构建物而非共享库按 apps/README.md 的原始定义apps目录用于容纳能够产出独立、类二进制输出的项目并被部署到其他位置projects that can produce independent, binary-like outputs deployed elsewhere。这带来两个关键推论不发布到 NPM这些项目通常设置private: true例如 apps/notifications/package.json、apps/odyssey-stats/package.json、apps/blaze-dashboard/package.json 均是如此不参与yarn start它们不属于 Calypso 开发服务器的启动链路需要按各自package.json中的脚本单独构建。与 apps 相对的是需要发布为 NPM 包可能被 Calypso 其他模块复用的共享代码统一放在/packages目录。monorepo 文档 给出了更完整的模块布局除apps、packages外还包括clientCalypso 主应用、desktopWordPress.com 桌面应用拥有独立的依赖树与yarn.lock以及test/e2e端到端测试包。从仓库现状可以验证这一布局。apps/目前包含 8 个子应用目录包名部署/用途apps/notificationsautomattic/notificationsWordPress.com 通知面板既内嵌于 Calypso也通过 iframe 在非 Calypso 站点运行apps/blaze-dashboardautomattic/blaze-dashboard经由 Jetpack 插件在 wp-admin 内提供的 Blaze 推广面板apps/odyssey-statsautomattic/odyssey-stats经由 Jetpack 插件在 wp-admin 内提供的 Calypso 统计apps/help-centerautomattic/help-center-app供 Jetpack 使用的帮助中心应用apps/agents-managerautomattic/agents-manager-app供 Jetpack 使用的 AI Agents 管理应用apps/wpcom-block-editorautomattic/wpcom-block-editorWordPress.com 集成场景的块编辑器工具集apps/happy-blockshappy-blocksWordPress.com 论坛、支持等站点上使用的块apps/o2-blocksautomattic/o2-blockso2 主题的 Gutenberg 扩展以 apps/notifications/README.md 为例它明确写道该面板直接在 Calypso 内部运行也通过iframe在非 Calypso 的 WordPress.com 站点上运行iframe 版本托管于https://wordpress.com/widgets/notifications/或遗留地址https://widgets.wp.com/notifications/。这正是部署到 Calypso 之外的典型场景。构建 Apps手动触发与主构建隔离apps 与 packages 在构建上的核心区别是packages 的prepare脚本会在仓库根目录执行yarn时自动运行而 apps不会。因此必须手动进入 app 目录构建这是 apps/README.md 中特别强调的一点。cd apps/app-name yarn build # 也可以运行 app 的 package.json 中任意其他脚本 # 例如 FSE 插件的开发与同步命令 yarn dev --sync从仓库中各 app 的实际脚本看yarn build通常被定义为生产构建且多数会串联构建 同步两步。以几个代表性应用为例apps/notifications/package.jsonbuild: NODE_ENVproduction yarn dev而dev内部调用calypso-apps-builder --localPath dist --remotePath /home/wpcom/public_html/widgets.wp.com/notifications即把dist产物同步到 WordPress.com 生产环境的 widgets 目录apps/blaze-dashboard/package.json 与 apps/odyssey-stats/package.json同样采用build: NODE_ENVproduction yarn dev模式目标路径分别为widgets.wp.com/blaze-dashboard/v1与widgets.wp.com/odyssey-stats/v1apps/wpcom-block-editor/package.json 则提供了两种构建build:wpcom-block-editorNODE_ENVproduction calypso-build与build:wpcom-block-editor-no-minifyNODE_ENVdevelopment calypso-build便于调试未压缩产物apps/happy-blocks/package.json 支持按块粒度构建例如build:pricing-plans、build:search-card、build:universal-header等通过calypso-build --env blockxxx指定。从源码结构可以看出这些构建统一基于automattic/calypso-build与automattic/calypso-apps-builder两个工作区依赖完成前者负责 webpack/babel 编译后者负责把本地产物同步到远端部署路径。monorepo 文档还提供了通过yarn workspace从仓库根目录直接构建某个 app 的等价写法yarn workspace automattic/wpcom-block-editor run build这在不想反复cd的场景下更为便捷。开发与同步--sync的沙盒工作流对于需要部署验证的 appapps/notifications/README.md 描述了典型的开发循环yarn dev --sync将开发构建同步到沙盒yarn build --sync将生产构建同步到沙盒。前提是你在~/.ssh/config中配置了名为wpcom-sandbox的别名且需要对widgets.wp.com域名做沙盒化sandbox处理。构建产物默认落在各 app 的dist目录。TeamCity 也会在每个提交上自动生成 app 构建产物可在 PR 检查中查找Notifications (WPCom Plugins)任务并进入 artifacts 标签获取。新增一个 App入口与规范apps/README.md 明确指出如果要在本目录新增项目只需新建一个子目录并遵循 Monorepo 文档 的约定。结合该文档一个 app或 package的标准布局是package.json # 模块的 package.json README.md # 模块说明文档 CHANGELOG.md # 变更日志 src/ # 源码目录 index.js # 导出模块全部能力 module-a.js # 具体模块 test/ # 测试目录需要特别注意的是monorepo 文档 对是否应该做成包给出了明确的门槛一个包应当只有一个清晰目的避免厨房水槽式的工具包应当有清晰、文档化的公共 API依赖要求如是否依赖 WP.com REST API、是否只能在特定上下文运行应在 README 中显式说明。这一准则同样适用于判断一个新项目应该放进apps/独立部署产物还是packages/可发布共享库。校验 package.jsonESLint 与例外机制package.json本身会被 ESLint 当作可校验对象apps/README.md 给出了校验命令yarn eslint apps/*/package.jsonmonorepo 文档 中的命令则同时覆盖 apps 与 packagesyarn eslint packages/*/package.json apps/*/package.json。这意味着所有新增 app 的package.json必须通过 lint 规则仓库中对应规则实现位于 packages/eslint-plugin-package-json常见的约束包括字段顺序、sideEffects声明、依赖声明方式等。如果需要豁免某些规则可以在 app 目录内添加./eslintrc.js文件并禁用相关规则——这是官方文档提供的标准例外途径。sideEffects 与 tree-shaking 的隐性要求虽然apps/README.md未展开但 monorepo 文档 对package.json中sideEffects字段有严格要求且直接影响生产构建结果如果包内包含css、scss文件必须将其列入sideEffects数组否则开发构建正常、但生产构建的 tree-shaking 会把这些样式文件丢弃。正确写法{ sideEffects: [ *.css, *.scss ] }仓库中的 app 也遵循这一实践例如 apps/help-center/package.json 声明了sideEffects: [ *.css, *.scss, ./config.js ]把config.js也显式标记为有副作用。测试与 CI 集成apps 的测试与主仓库测试共用同一套工具链。以 apps/notifications/package.json 与 apps/odyssey-stats/package.json 为例均提供test:js脚本yarn run -T test-apps apps/notifications yarn run -T test-apps apps/odyssey-stats其中-T表示在 Monorepo 根目录执行Yarn v2 的--top-level简写test-apps是根 package.json 中定义的聚合测试脚本。在 CITeamCity侧各 app 通过teamcity:build-app脚本接入构建流水线。部分 app 还附加了质量门禁例如 apps/odyssey-stats/package.json 的teamcity:build-app为yarn run build yarn run test:size yarn run verify:css-scope即在构建后还会执行size-limit体积检查与 CSS 作用域校验脚本见 apps/odyssey-stats 下的bin/verify-css-scope.js确保嵌入 wp-admin 的产物体积与样式隔离可控。这表明 apps 目录并非简单的旁路项目而是与 Calypso 共享工程规范的一等公民。小结apps/目录是 wp-calypso Monorepo 中独立部署物的标准化家园它与packages/以是否发布 NPM、是否参与主构建为分界线每个 app 通过自己的package.json脚本通常基于calypso-buildcalypso-apps-builder完成构建与远端同步新增 app 遵循 Monorepo 文档 的目录与package.json规范并接受 ESLint 的统一校验。对于希望在 Calypso 之外如 Jetpack 插件、widgets.wp.com域名部署前端功能模块的开发者而言这里就是标准入口——动手前先读 apps/README.md 与 monorepo.md再对照任一现有 app如 notifications的package.json起步是最稳妥的路径。赞分享前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载相关推荐wp-calypso Blaze Dashboard 独立应用架构解析wp-admin 内嵌广告管理 SPA 的构建与开发实践wp calypso Blaze Dashboard 独立应用架构解析wp admin 内嵌广告管理 SPA 的构建与开发实践 导读 Blaze Dashbo前端CMSwp-calypso Blaze Dashboard 独立应用全指南目录架构、hashbang 路由、Gridicon 替换与构建发布实战wp calypso Blaze Dashboard 独立应用全指南目录架构、hashbang 路由、Gridicon 替换与构建发布实战 Blaze Das前端CMSOpenUtau终极指南开源虚拟歌手编辑器的完整技术手册OpenUtau终极指南开源虚拟歌手编辑器的完整技术手册 您是否曾经面临传统虚拟歌手软件功能受限、操作复杂、跨平台支持不足的困扰OpenUtau作为现代化的前端CMS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考