wix-cli-app-validation

Wix 应用验证

通过四步顺序工作流验证 Wix CLI 应用：安装软件包、检查 TypeScript 编译、构建和预览。

验证工作流

按顺序执行以下步骤。如果任何步骤失败，请停止并报告错误。

步骤 1：安装软件包

继续构建前，确保已安装所有依赖项。

检测软件包管理器：

• 检查是否存在 package-lock.json → 使用 npm
• 检查是否存在 yarn.lock → 使用 yarn
• 检查是否存在 pnpm-lock.yaml → 使用 pnpm
• 如果找不到锁文件，则默认使用 npm

运行安装命令：

# For npm
npm install

# For yarn
yarn install

# For pnpm
pnpm install

成功标准：

• 退出代码为 0
• 所有依赖项均已成功安装
• 没有缺少对等依赖项的警告（除非预期会有）
• node_modules 目录存在，且包含预期的软件包

**失败时：**报告安装错误，查看错误时的调试日志以获取详细诊断信息，然后停止验证。常见问题：

• 网络连接问题
• 锁文件损坏
• 版本冲突
• 缺少 Node.js 或软件包管理器

步骤 2：TypeScript 编译检查

运行 TypeScript 编译器以检查类型错误。

完整项目检查：

npx tsc --noEmit

定向检查（特定文件/目录）：

实现特定扩展后进行验证时，可以只对这些文件运行 TypeScript 检查：

# Check specific directory
npx tsc --noEmit src/extensions/dashboard/pages/survey/**/*.ts src/extensions/dashboard/pages/survey/**/*.tsx

# Check dashboard pages only
npx tsc --noEmit src/extensions/dashboard/pages/**/*.ts src/extensions/dashboard/pages/**/*.tsx

# Check site widgets only
npx tsc --noEmit src/extensions/site/widgets/**/*.ts src/extensions/site/widgets/**/*.tsx

# Check dashboard modals only
npx tsc --noEmit src/extensions/dashboard/modals/**/*.ts src/extensions/dashboard/modals/**/*.tsx

# Check backend only
npx tsc --noEmit src/extensions/backend/**/*.ts

适合使用定向检查的情况：

• 实现单个扩展后（更快获得反馈）
• 调试特定区域中的类型错误时
• 迭代开发期间

适合使用完整项目检查的情况：

• 最终验证前
• 更改影响共享类型时
• 构建/部署前

成功标准：

• 退出代码为 0
• 没有 TypeScript 编译错误
• 所有类型检查均通过

**失败时：**报告具体的 TypeScript 错误，然后停止验证。常见问题：

• 预期类型与实际类型不匹配
• 导入的模块缺少类型声明
• 泛型类型参数不正确
• 声明的类型中不存在相应属性
• 函数签名不兼容

步骤 3：构建验证

运行构建命令并检查编译错误：

npx wix build

成功标准：

• 退出代码为 0
• 没有 TypeScript 错误
• 没有缺少的依赖项

**失败时：**报告具体的编译错误，查看错误时的调试日志以获取详细诊断信息，然后停止验证。

步骤 4：预览部署

启动预览服务：

npx wix preview

成功标准：

• 预览服务成功启动
• 已生成预览 URL（网站和控制面板各一个）

**提取 URL：**解析终端输出，找到两个预览 URL。查找以下模式：

• 网站预览：Site preview: https://... 或 Site URL: https://...
• 控制面板预览：Dashboard preview: https://...、Preview URL: https://... 或 Your app is available at: https://...

提取这两个 URL 并提供给用户，以便手动验证。

**失败时：**报告预览启动错误，查看错误时的调试日志以获取详细诊断信息，然后停止验证。

验证报告

完成所有步骤后，提供总结：

通过：

• 依赖项：✓ 所有软件包均已成功安装
• TypeScript：✓ 没有编译错误
• 构建：✓ 编译成功
• 预览：✓ 正在 [URL] 运行

失败：

• 指明失败的步骤
• 提供具体错误消息
• 建议修复步骤

错误时的调试日志

验证步骤失败时（退出代码非零、输出错误，或 CLI 崩溃/卡住），请检查项目根目录中的 .wix/debug.log，获取完整错误跟踪信息。仅在发生错误时读取此文件——步骤通过时，或终端输出已明确说明错误时（例如，简单明了的 TypeScript 类型错误），请跳过此操作。

.wix/ 目录由 Wix CLI 自动创建，其中包含内部配置和日志文件。请勿编辑此目录，但排查问题时可以读取 debug.log。

Read: .wix/debug.log

# If the file is large, read the last 100 lines for the most recent errors
Read: .wix/debug.log (with offset to the end)

常见问题

问题	原因	解决方案
软件包安装失败	缺少锁文件、网络问题或 node_modules 损坏	删除 node_modules 和锁文件，然后重新安装
TypeScript 编译失败	类型不匹配、缺少声明或类型不正确	修复 npx tsc --noEmit 输出中显示的 TypeScript 错误
构建失败	TypeScript 错误、缺少依赖项或 CLI 内部错误	修复源代码中的 TypeScript 错误；对于不明显的失败，请检查 .wix/debug.log
预览无法启动	端口冲突、配置问题或 CLI 内部错误	检查 wix.config.json；如果不清楚原因，请检查 .wix/debug.log 了解详情
预览中出现控制台错误	运行时异常	检查浏览器控制台输出
UI 未渲染	组件错误	检查组件代码和导入语句
CLI 报错但没有明确提示	终端输出被截断	阅读 .wix/debug.log，查看完整错误跟踪和堆栈详情
更改配置后出现不明失败	CLI 状态过时	阅读 .wix/debug.log 进行确认，然后删除 .wix/ 并重新构建