搭建你的开发环境

根据你的需求选择合适的开发工作流来开发 Lightning Web Components。我们推荐使用 Salesforce DX 工具，但如果你处于不支持这些工具的环境中，你仍然可以使用自己喜欢的代码编辑器，并通过自己的工具部署到组织。然而，你不能在 Developer Console 中开发 Lightning Web Components。

推荐学习路径：在 Trailhead 上完成 Set Up Your Lightning Web Components Developer Tools 项目和 Quick Start: Lightning Web Components 项目，快速上手。

安装代码编辑器并设置 Linting

安装代码编辑器

我们强烈推荐使用 Visual Studio Code，因为它的 Salesforce Extension Pack 为 Salesforce CLI、Lightning 组件框架、Apex 和 Visualforce 提供了强大的开发功能。

设置 ESLint Linting

Linting 在你编辑代码时实时发现错误，在编译之前就帮你远离反模式、遵循最佳实践。Salesforce 创建了专门的 ESLint 规则来减少 Lightning Web Components 编程错误。

重要：建议尽快将项目迁移到 ESLint v9。从 Spring '26 开始，所有新的 ESLint 规则和错误修复将只支持 ESLint v9。详见 LWC Now Supports ESLint v9 和 ESLint v9 迁移指南。

Linting 配置要点

如果使用 Salesforce DX 项目，linting 已自动包含，无需手动设置
如果不使用 Salesforce DX 项目，从命令行安装 ESLint 规则：npm install
有三种配置级别可选（base / recommended / strict），查看 eslint-config-lwc README 选择适合你的级别
在 /force-app/main/default/lwc/.eslintrc.json 中设置配置级别
运行 linting：npm run lint（项目中必须至少有一个 LWC 组件）

# 安装 ESLint 规则
npm install

# 运行 linting（必须至少有一个组件）
npm run lint

如果你在为 Lightning Web Security（LWS）开发组件，还需要安装 LWS 专用的 ESLint 规则。

设置开发组织与调试模式

开发组织选项

Developer Edition 组织（免费）

在 developer.salesforce.com/signup 注册
适合学习和个人项目

Scratch Org（推荐用于 DX 工作流）

短期 Salesforce 环境，可快速创建用于开发特定功能
源追踪（Source Tracking）：只推送变更的文件，而非全部
从 Winter '23 开始，LWS 在 Scratch Org 中默认启用
需要配置 Dev Hub

非 Scratch Org（Sandbox 等）

无源追踪 —— 部署所有指定的元数据，而不仅仅是变更
可以从中检索代码
使用 sf project deploy start 而非 push

启用调试模式（Debug Mode）

启用调试模式后，框架 JavaScript 代码不会被压缩，使其更易于阅读和调试。调试模式还会为某些警告和错误添加更详细的输出。

注意：仅对正在积极开发或调试 JavaScript 的用户启用调试模式。启用后 Salesforce 会变慢。

设置步骤

在 Salesforce 中，从设置（Setup）的快速查找框中输入 Debug Mode，选择 Debug Mode
在用户列表中，找到需要启用调试模式的用户（可使用标准列表视图控件筛选）
勾选需要启用调试模式的用户旁边的复选框
点击 Enable

使用 Salesforce DX 工具开发

我们推荐使用 Salesforce DX 工具以获得最紧密集成的开发体验。该工作流包含以下工具链：

Salesforce CLI —— 命令行界面
VS Code + Salesforce Extension Pack —— 代码编辑器与扩展
Salesforce DX 项目 —— 标准化的项目结构
Scratch Org 或 Sandbox Org —— 开发和测试环境

核心优势

源追踪（Scratch Org）：只推送变更的文件
版本控制集成
自动包含 Linting
完整的 CLI 命令：create、push、pull、deploy、retrieve

VS Code 中的 SFDX 命令

按 Command + Shift + P，输入 sfdx，可访问以下命令：

SFDX: Create Project —— 创建项目
SFDX: Authorize a Dev Hub —— 授权 Dev Hub
SFDX: Create a Default Scratch Org —— 创建默认 Scratch Org
SFDX: Create Lightning Web Component —— 创建 LWC
SFDX: Push Source to Default Scratch Org —— 推送源码
SFDX: Open Default Scratch Org —— 打开组织

提示：所有命令也可以从命令行直接运行。推荐先完成 Trailhead 上的 Quick Start: Lightning Web Components 项目。

安装 Salesforce CLI

按照 Salesforce CLI 安装指南在你的操作系统上安装 CLI
验证安装版本：
```
sf plugins --core
```
输出示例：@salesforce/cli 2.24.3 (core)

在 Scratch Org 中开发

Scratch Org 是短期 Salesforce 环境，你可以为特定功能快速创建。推送到 Scratch Org 时，只有变更的文件会被推送。以下是完整的 10 步工作流：

步骤 1：创建 Salesforce DX 项目

cd PATH/TO/YOUR/SFDX/PROJECTS
sf project generate --name MyLWC
cd MyLWC

步骤 2：安装并配置 Linting

npm install
# 在 .eslintrc.json 中设置配置级别
npm run lint

步骤 3：在组织中启用 Dev Hub

Dev Hub 是你和团队用来创建和管理 Scratch Org 的主要 Salesforce 组织。从设置中输入 Dev Hub，选择 Dev Hub，点击 Enable。启用后不可禁用。仅支持的版本可用。

步骤 4：授权 Dev Hub

sf org login web -d -a LWC-Hub

"LWC-Hub" 是 Dev Hub 组织的别名，可在后续 CLI 命令中使用。只需授权一次。

步骤 5：创建默认 Scratch Org

sf org create scratch -s -f config/project-scratch-def.json -a "LWC"

"LWC" 是 Scratch Org 的别名。project-scratch-def.json 是默认的 Scratch Org 定义文件。从 Winter '23 开始，LWS 在新 Scratch Org 中默认启用。

步骤 6：创建 Lightning Web Component

sf lightning generate component --type lwc -n myComponent -d force-app/main/default/lwc

组件创建在 force-app/main/default/lwc 文件夹下。

步骤 7：推送源码到 Scratch Org

sf project deploy start

只有变更的文件被推送。记得先保存代码。

步骤 8：打开 Scratch Org

sf org open

步骤 9：从 Scratch Org 拉取源码

sf project retrieve start

步骤 10：重复迭代

推送变更 → 硬刷新浏览器 → 查看效果 → 继续开发。

在 Scratch Org 中创建 Hello World 组件

让我们从头创建一个 Hello World 组件，并使用 Lightning App Builder 将其添加到 Lightning 页面中。

步骤 1：创建项目并授权

sf project generate --name lwc-hello-world
cd lwc-hello-world
sf org login web
sf org create scratch -s -f config/project-scratch-def.json -a "lwchelloworld"

步骤 2：创建 helloWorld 组件

sf lightning generate component --type lwc -n helloWorld -d force-app/main/default/lwc

命名规则：使用 camelCase 命名组件（helloWorld），它在 HTML 中映射为 kebab-case（<c-hello-world>）。

步骤 3：编写 JavaScript 文件

在 helloWorld.js 中添加：

import { LightningElement, api } from "lwc";

export default class HelloWorld extends LightningElement {
  @api name;
}

@api 装饰器将 name 属性设为公开，使其可在 Lightning App Builder 中配置。

步骤 4：编写 HTML 模板

在 helloWorld.html 中添加：

<template>
  <lightning-card title="HelloWorld" icon-name="custom:custom14">
    <div class="slds-card__body slds-card__body_inner">
      Hello, {name}!
    </div>
  </lightning-card>
</template>

{name} 语法将 HTML 模板中的 name 属性绑定到 JavaScript 类中的 name 属性。lightning-card 基础组件提供了美观的卡片样式。

步骤 5：配置组件以支持 Lightning App Builder

编辑 helloWorld.js-meta.xml：

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>45.0</apiVersion>
    <isExposed>true</isExposed>
    <masterLabel>Hello World</masterLabel>
    <description>Add a classic greeting to any page.</description>
    <targets>
      <target>lightning__AppPage</target>
    </targets>
    <targetConfigs>
      <targetConfig targets="lightning__AppPage">
        <property name="name" type="String" label="Name"
            placeholder="World"
            description="Enter the name of the person to greet."/>
      </targetConfig>
    </targetConfigs>
</LightningComponentBundle>

步骤 6：推送并打开

sf project deploy start
sf org open

步骤 7：将组件添加到 Lightning 页面

在 Scratch Org 的设置中，输入 bui，点击 Lightning App Builder
点击 New，选择 App Page，点击 Next
输入标签 Hello World，选择 Three Regions，点击 Finish
将 Hello World 组件从 Custom 组件列表拖到页面的一个区域
选中组件，输入一个 Name 值
可以拖入多个 Hello World 组件，为每个设置不同的名称
点击 Save and Activate
在激活页面选择图标，点击 Lightning Experience，将页面添加到 Lightning Bolt 应用，点击 Save
从 App Picker 点击 Bolt Solutions，点击 Hello World 标签页查看页面

修改代码 → 推送 → 硬刷新浏览器即可看到更改。

在非 Scratch Org 中开发

非 Scratch Org 包括 Sandbox、Developer Edition 组织和生产组织。与 Scratch Org 不同，这些组织没有源追踪，你需要部署所有指定的元数据，而不仅仅是变更的文件。

设置步骤

创建 Salesforce DX 项目（同 Scratch Org）
安装并配置 Linting（同 Scratch Org）

创建组件

sf lightning generate component --type lwc -n myComponent -d force-app/main/default/lwc

部署源码到组织

sf project deploy start -d <PATHTODEPLOY> -o <ORGUSERNAME>

# 示例：部署整个项目到组织
sf project deploy start -d force-app -o example@force.com

部署指定路径中的所有文件（不仅仅是变更的文件）。

从组织检索源码

sf project retrieve start -d <PATHTORETRIEVE> -o <ORGUSERNAME>

与 Scratch Org 的主要区别

特性	Scratch Org	Non-Scratch Org
源追踪	支持（只推送变更文件）	不支持（部署所有指定元数据）
Dev Hub	必需	不需要
推送/部署	`sf project deploy start`（push）	`sf project deploy start -d -o`
拉取/检索	`sf project retrieve start`（pull）	`sf project retrieve start -d -o`
项目结构	相同	相同

迭代流程

部署变更 → 硬刷新浏览器 → 查看效果 → 继续开发。

感谢阅读本指南。如需继续学习，请参阅下一章：运行实时组件预览。

搭建你的开发环境 — Salesforce LWC 开发者环境配置指南