用途:梳理 Bitrix 框架中 JS/CSS 扩展的创建、配置与加载方式,基线为 main 23.0+,已验证 main 26.800.0、ui 26.687.0。
主要能力:扩展 ID 的每个点对应目录层级(Extension::getPath()),如 vendor.module.editor 映射到 js/vendor/module/editor/,优先搜索 /local/js/,再搜索 /bitrix/js/;ID 至少两段,每段为 [a-z0-9_-],带点的目录无法按 ID 加载。扩展可位于项目、分发模块或内核,内核路径不应直接修改。
使用方式:在扩展目录用 bitrix create 生成骨架、bitrix build 构建(@bitrix/cli)。bundle.config.js 定义 input、output、namespace、browserslist 等;CSS 通过在入口 import './style.css'; 引入。构建会重写 config.php(js、css、rel 来自 import),除非设置 adjustConfigPhp: false。config.php 支持 js、css、rel、skip_core、settings、lang_additional、oninit、controllerEntrypoint 等键。语言短语放在 lang/<LANGUAGE_ID>/config.php 的 $MESS 中,JS 通过 Loc.getMessage('VENDOR_EDITOR_TITLE') 读取。加载用 Extension::load([...]) 或 Runtime.loadExtension(...),后者解析为合并后的导出。
适用场景:需要遵循 ID 到目录映射、构建产物与配置同步、语言短语与设置传递规范的 Bitrix 扩展开发。
限制:未知 ID 静默失败;不应通过 script src 或 Asset::addJs() 直接加载 /local/js/ 或 /bitrix/js/ 文件;dist/ 需在 src/ 变更后重新构建并随 bundle.config.js 部署;应在 rel 中声明依赖;安装与卸载需注意递归复制与删除。