wix-cli-extension-registration

Wix 应用注册

创建任何扩展文件后，都必须更新主 src/extensions.ts 文件，以便向应用注册该扩展。

注册为何重要

Wix CLI 通过 src/extensions.ts 文件发现扩展——它是唯一入口，用于告知构建系统有哪些扩展。未注册时：

• 控制面板页面不会显示在侧边栏中
• 网站小组件不会显示在 Wix Editor 中
• 服务插件不会在结账流程中被调用
• 事件处理程序不会收到 Webhook 投递
• 嵌入式脚本不会注入网站页面

“我的扩展无法正常工作”最常见的原因，就是此文件中缺少 .use() 调用。

简单模式（推荐用于小型应用）

src/extensions.ts - 直接导入并注册扩展：

import { app } from "@wix/astro/builders";
import { dataExtension } from "./extensions/data/extensions.ts";
import { dashboardpageMyPage } from "./extensions/dashboard/pages/my-page/extensions.ts";
import { embeddedscriptMyScript } from "./extensions/site/embedded-scripts/my-script/extensions.ts";

export default app()
  .use(dataExtension)
  .use(dashboardpageMyPage)
  .use(embeddedscriptMyScript);

每个新扩展的步骤：

1. 从其 extensions.ts 文件导入扩展
2. 在应用链中添加 .use(extensionName)
3. 将多个扩展串联起来

高级模式（适用于大型应用）

src/index.ts - 重新导出所有扩展：

export { dashboardpageMyPage } from "./extensions/dashboard/pages/my-page/extensions";
export { embeddedscriptMyScript } from "./extensions/site/embedded-scripts/my-script/extensions";
export { dataExtension } from "./extensions/data/extensions";

src/extensions.ts - 以编程方式注册所有扩展：

import { app } from "@wix/astro/builders";
import * as allExtensions from "./index";

const extensionList = Object.values(allExtensions);

const appBuilder = app();
extensionList.forEach((extension) => {
  appBuilder.use(extension);
});

export default appBuilder;

无需注册的扩展类型

以下扩展类型不需要 extensions.ts 文件：

• Backend API - Astro 服务端点会自动发现

命名约定

扩展导出名称遵循以下模式：{extensiontype}{CamelCaseName}

示例：

• dashboardpageCartPopupManager
• dashboardpluginBlogPostsBanner
• dashboardmenupluginExportPosts
• embeddedscriptCouponPopup
• sitewidgetCountdownWidget
• sitepluginProductBadge
• ecomshippingratesCustomShipping

类型前缀是小写且不含分隔符的扩展类型名称。

故障排除

症状	原因	解决方法
扩展完全没有显示	缺少 .use() 调用	在 src/extensions.ts 中添加导入和 .use(extensionName)
构建时报错“Cannot find module”	导入路径错误	确认导入路径与实际文件位置一致（相对于 src/）
扩展已注册但无法正常工作	导出名称不匹配	确保扩展文件中的导出名称与 extensions.ts 中的导入名称一致
有多个扩展，但只有部分生效	链不完整	检查每个扩展是否都同时具有导入和 .use() 调用
.use() 上出现 TypeScript 错误	导出类型错误	确保扩展文件使用正确的构建器方法（例如，extensions.dashboardPage() 而不是 extensions.embeddedScript()）