运行实时组件预览 — Salesforce LWC Live Preview 与开发最佳实践

运行实时组件预览（Live Preview）

使用 Live Preview 在实时浏览器预览中开发 Lightning Web Components。当你保存源代码更改时，Live Preview 会自动更新浏览器或 IDE 中的组件，让你无需部署代码或手动刷新即可快速迭代。

注意：Live Preview 此前被称为 Local Dev，在 Spring '26 中重新命名以反映其实时预览的特性。使用 Live Preview 不需要部署代码。

Live Preview 概述与设置

四种 Live Preview 工具

工具	用途	CLI 命令
Lightning App 预览	在浏览器中预览 Lightning 应用（桌面或移动端）	sf lightning dev app
Experience Sites 预览	在浏览器中预览 Experience LWR 站点	sf lightning dev site
单组件预览	在浏览器中隔离预览单个 LWC	sf lightning dev component
VS Code 扩展	在 VS Code 面板中预览 LWC 或 React 组件	（IDE 内操作）

支持环境

• 可用于生产组织、Sandbox 和 Scratch Org（推荐仅在 Sandbox 和 Scratch Org 中使用）
• 支持 Lightning 应用、Experience 站点、LWC 和 React 组件

设置步骤

1. 安装 Salesforce CLI（CLI 会自动安装 Live Preview 插件）
2. 启用 Live Preview：首次运行任意 Live Preview 命令时，CLI 会提示你启用该功能，按 Enter 或输入 y 确认
3. 确保项目结构正确：项目中必须有 lwc 目录（通常位于 force-app/main/default/lwc）

提示：建议在运行 Live Preview 之前执行 sf update 以确保使用最新版本的 CLI 命令。首次使用？在 Trailhead 上完成 Set Up Your Lightning Web Components Developer Tools 项目。

Lightning App 与 Experience Sites 实时预览

Lightning App 实时预览

在桌面环境或 Salesforce 移动应用（iOS 或 Android）上预览 Lightning 应用。

sf lightning dev app

命令标志

标志	必需/可选	说明
-o, --target-org	必需	目标组织的用户名或别名。示例：--target-org myOrg
-n, --name	可选	要预览的 Lightning Experience 应用名称。含空格时加引号：--name "SDO - Consumer"
-t, --device-type	可选	设备类型：desktop、ios、android
-i, --device-id	可选	指定移动设备 ID（如 "iPhone 15 Pro Max"），默认为第一个可用设备

移动环境预览

• iOS 模拟器（仅 Mac）：从 Mac App Store 安装 Xcode，在 Xcode 中下载 iOS 模拟器，运行 sf lightning dev app --device-type ios
• Android 模拟器：安装 Android Studio，运行 sf lightning dev app --device-type android
• CLI 会在需要时自动提示在模拟器上安装 Salesforce 移动应用

Experience Sites 实时预览

自动基于站点当前状态生成并下载静态包，仅在桌面环境中支持。

sf lightning dev site

重要：在运行 Experience Sites Live Preview 之前，必须先发布你的 Experience LWR 站点。

命令标志

标志	说明
-o, --target-org	目标组织（必需）
-n, --name	站点名称（可选，含空格时加引号）
--get-latest	更新本地缓存为组织中的最新站点版本（用于查看最近的 Experience Builder 更改）
--ssr	Spring '26 起不再支持，请勿使用

单组件与 VS Code 实时预览

单组件实时预览

在浏览器中隔离预览单个 LWC，组件可以访问平台模块，包括公共 Lightning Data Service wire adapters、@salesforce scoped modules 和 Apex controllers。

sf lightning dev component

命令标志

• -o, --target-org（必需，从 Winter '26 开始）—— 目标组织
• -n, --name（可选）—— 组件名称
• --json（可选）—— 格式化输出为 JSON

浏览器工具栏工具

• 更改组件尺寸：点击设备图标使用预设尺寸，或拖动三边的调整条设置自定义尺寸
• 性能模式：切换 Performance Mode 以无页面 UI 元素的方式预览组件（点击浏览器后退按钮退出）
• 项目组件侧边栏：点击右上角菜单图标打开，列出项目中可预览的所有组件

VS Code Live Preview 扩展

在 VS Code 或 Code Builder 环境的专用面板中实时预览 LWC 或 React 组件。保存本地更改时预览自动更新。

三种启动方式

1. IDE 上下文菜单：在 VS Code Explorer 中右键点击组件目录或文件 → SFDX: Open in Lightning Preview
2. 命令面板：打开命令面板（Cmd+Shift+P），搜索 SFDX: Open in Lightning Preview
3. Agent 集成：如果使用 Agentforce Vibes，可以指示 Agent 在代码更新完成后自动打开组件预览

提示：考虑将 Live Preview 与 Agentforce Vibes 配合使用，AI 助手可以帮助你编写、重构和测试代码，并直接在 Lightning Preview 面板中打开组件。

Live Preview 注意事项与限制

自动加载的更改（无需刷新）

更改类型	示例
基本 HTML 修改	修改组件属性，如 title="Hello" 改为 title="Goodbye"
新的组件引用	在标记中添加 <lightning-button></lightning-button>
基本 CSS 修改	修改 styling hooks 值
导入新的纯 CSS 组件	添加仅包含 CSS 文件和配置文件的 cssLibrary 组件
不影响公共 API 的 JS 更改	使用新的事件处理器或修改现有事件处理器逻辑
添加/删除组件文件	从 Spring '25 开始自动检测

需要手动刷新的更改

• 添加新的 @api 属性或方法
• Wire adapter 相关更改（配置更新、导入新 adapter、添加 @wire、修改 GraphQL 查询）
• 导入新的 @salesforce scoped modules
• 更新 .js-meta.xml 文件
• 修改 service component library

处理方式

• App/Site 预览：使用 sf project deploy start 部署更改 + 重启 Live Preview 服务器
• 组件预览：刷新浏览器页面

其他注意事项

• Live Preview 仅支持 LWC，不能用于测试 Aura 组件
• 仅自动更新 .js、.html、.css 文件（其他类型如 .js-meta.xml 需要部署）
• 从 Spring '25 开始，不再将构建保存到静态资源目录（之前会计入 250 MB 组织限制）
• 新增/删除文件从 Spring '25 开始自动检测
• 不支持 Landing Pages 预览

移动开发与自定义部署

移动组件开发

在开发 Lightning Web Components 时，不仅要在桌面上验证，还要在移动设备上进行验证。使用 Salesforce CLI Mobile Extensions 插件在虚拟移动设备上预览组件，并下载 Salesforce 移动应用的虚拟设备构建来预览组件在 Salesforce 中与其他组件的共存效果。

移动端特殊考虑

• 更小的屏幕尺寸
• 不同的输入方式
• 可能有限或零连接
• 与桌面端不同的功能和方案

参考：准备好构建移动友好功能时，请参阅 Mobile and Offline Developer Guide，这是进行移动开发时的重要参考。

使用自己的工具部署

不使用 Salesforce DX 工具？可以使用 Metadata API 以自己的方式部署 LWC：

1. 创建包含以下内容的 zip 归档文件：
   • 组件文件
   • package.xml 清单文件
   • Metadata API 类型为 LightningComponentBundle
2. 使用 ANT Migration Tool 或自定义工具将组件部署到 Sandbox 或 Scratch Org

注意：不使用 Salesforce CLI 意味着你会失去源追踪（Change Tracking）功能，需要自己实现对应的解决方案。建议使用 GitHub 监控代码更改，使用 Sandbox 的 Auditing 功能跟踪数据和字段更改。如果使用 Prettier，建议添加 pre-commit hook 确保代码格式一致。

最佳实践与学习资源

LWC 开发最佳实践

• 开发者最佳实践清单 —— 推动一致性并提升开发者技能
• LWC 性能最佳实践 —— 优化渲染和数据加载
• 提升你的 LWC 技能 - Part 1
• 提升你的 LWC 技能 - Part 2
• LWC 错误处理最佳实践（视频）
• 设计模式与可重用 LWC（视频）

Lightning Web Components Recipes

一组易于理解的代码示例，每个示例以最少的代码行数演示特定任务，同时遵循最佳实践。每个示例都提供 View Source 链接直达 GitHub 代码。涵盖：组合、状态管理、事件、数据访问和导航。

github.com/trailheadapps/lwc-recipes

Trailhead 学习路径

• Build Lightning Web Components 路径 —— 动手创建 LWC
• Troubleshoot Lightning Web Components 路径 —— 排查问题并学习最佳实践

E-Bikes 示例应用

展示如何使用 LWC 构建应用并与 Salesforce Experiences 集成。E-Bikes 是一家虚构的电动自行车制造商，该应用帮助他们使用丰富的用户体验管理产品和经销商订单。

github.com/trailheadapps/ebikes-lwc

感谢阅读本指南。如需继续学习，请参阅下一章：创建 Lightning Web Components。