Upgrade API Version & Versioning Considerations

我们来看这一页很重要的内容，是关于API版本的。这听起来可能有点技术，但其实你把它想成是咱们组件的一个“系统版本号”就行了，很简单。 想象一下，Salesforce这个平台每年都会更新好几次，每次更新都可能带来一些新功能，或者稍微调整一下底层的运作方式。为了让你的组件知道该按哪一套“规矩”来运行，我们就给它设定一个API版本。 那这个版本的升级，有个非常关键的黄金法则，你一定要记住：，一次只升一个版本，并且每一次升级后都要仔细验证。， 为什么？因为Salesforce的版本升级很聪明。比如你现在的组件是从58.0版本升级到59.0版本，如果Salesforce打算在60.0版本里彻底改掉某个功能，它不会直接让你的组件报错不能用。它会先在一个版本里给你一个“警告”。这个警告就像是个温馨提醒，告诉你：“嘿，你这个写法要过时了，得赶紧换换。” 如果你不理它，继续升下个版本，那这个“警告”就会立刻变成一个“错误”，你的组件可能就打不开了。所以，一次只跨一步，能让你安全地处理掉这些警告。 这个API版本的变革，是从59.0版本开始支持的，一直到最新的63.0版本，也就是Spring '25的版本。在每一个版本发布时，官方文档里都会清楚列出“重大更改”，也就是那些可能会让你的组件出错的变化，升级前最好去看一眼。 接下来，还有几个你以后可能会遇到的实际状况，得心里有个数： 第一，同一个页面上，不同的组件完全可以跑在不同的API版本上。你的新组件可以用最新的61.0版本，旁边一个老组件可能还在用58.0版本，它们能和平共处，互不干扰。 第二，有一个默认行为要记一下。如果你的组件版本号写的是低于58.0的，系统会自动把它当作58.0来运行。这就像一个最低保障线。 第三，千万别耍小聪明，直接把版本号写成一个很未来的版本，比如64.0。编译器不认识它，会直接报一个保存错误，根本不让你保存。 那么，这个API版本控制到底写在哪儿，又对谁有效呢？这才是关键。 它是写在组件的`[组件名].js-meta.xml`这个配置文件里的。请特别注意，这个版本控制，只对Lightning Web Components有效，而且只在Lightning Experience主界面或者Experience Builder站点构建器里运行时才起作用，。它不适用于Aura组件，也不适用于在LWR站点上运行的LWC组件。 说到LWR，要特别提醒一下，LWR非常独特，它像一个先锋派，永远使用最新的API版本。你根本没法通过文件配置来控制它，它会自动升级。 好，总结一下这一页的核心：谨慎地、一步一步地通过修改`.js-meta.xml`文件来递增API版本，及时处理警告。记住，这只管得住LWC在核心平台上的行为，管不住LWR，也跟Aura没关系。清楚了这一点，版本升级就没什么可怕的了。