bitrix-project-structure

项目结构与自动加载

基线：main 23.0+ · 已验证：main 26.800.0

根目录

• /bitrix/ — 内核和市场模块；会被更新替换。切勿编辑（bitrix-framework）。
• /local/ — 所有项目代码；/local/ 中相同相对路径的文件优先于 /bitrix/ 中的文件。
• /upload/ — 用户／模块文件。

/local/
├── modules/<vendor>.<module>/   # project code lives in modules (bitrix-modules)
├── components/<ns>/<name>/      # bitrix-components
├── templates/<site_tpl>/        # site templates, component template overrides
├── routes/web.php               # bitrix-routing
├── js/<vendor>/<module>/<ext>/  # extension id vendor.module.ext (bitrix-extensions)
├── activities/                  # bizproc activities (also activities/custom)
├── gadgets/<ns>/<name>/         # desktop gadgets
├── blocks/                      # landing blocks repo
├── php_interface/
│   ├── init.php                 # every hit, before page code
│   ├── dbconn.php               # Since main 24.100 here; kernel constants
│   ├── after_connect_d7.php     # after the "default" DB connect only
│   └── user_lang/<lang>/lang.php # phrase overrides
├── .settings.php                # replaces /bitrix/.settings.php (bitrix-settings)
└── .settings_extra.php

为 /local/php_interface/ 设置与 /bitrix/php_interface/ 相同的访问保护。

php_interface 文件

• init.php：仅放置模块加载前需要的常量，以及不属于任何模块的钩子对应的运行时 addEventHandler()。其他内容应放入模块（install/、include.php、.settings.php）。
• after_connect_d7.php 会在 default 连接对象内部被引入：使用 $this->queryExecute("SET …")（字符集、sql_mode、时区）。只会运行一个文件 — /local 中的副本会禁用 /bitrix 中的文件，因此要将其中的语句一并迁移。其他连接通过 connections 中的 'include_after_connected' => '/abs/path.php' 运行各自的文件。

加载模块（Loader）

情况	调用
必需模块；加载失败即为错误	Loader::requireModule('vendor.module') — 抛出 LoaderException
可选集成	if (Loader::includeModule('crm')) { … }
共享软件／演示版状态	Loader::includeSharewareModule()

如果模块未在 b_module 中注册（仅有文件还不够），或其 include.php 返回 false，includeModule() 会返回 false。成功时，它会注册 PSR-4 根目录，引入 include.php，并注册模块的 services。在入口处（控制器、Agent、命令）加载一次，不要在服务深层加载。旧版 CModule::IncludeModule() 仅用于兼容。

模块 lib/ 中的 PSR-4

• 根目录：vendor.module → Vendor\Module\ → lib/；单词模块 mymodule → Bitrix\Mymodule\。
• 文件夹对应命名空间段，文件对应类：Vendor\Module\Public\Service\PostService → lib/Public/Service/PostService.php。
• Loader 会先尝试大小写完全匹配的路径，然后尝试全小写路径（内核混用这两种风格；从 main 26.600 起，许多内核 lib/ 目录采用 PascalCase）。PostTable 也会按 post.php 查找。
• 切勿通过路径 require 内核 lib/ 文件 — 内核更新可能会重命名这些文件（例如，26.200 中列表相关文件改为 PascalCase）。
• 非 PSR-4 旧版代码：在 include.php 中使用 Loader::registerNamespace('Vendor\\Legacy', $absDir) 或 Loader::registerAutoLoadClasses('vendor.module', ['COldClass' => 'classes/old.php'])。

Composer

• 在 DOCUMENT_ROOT 外放置 composer.json（例如项目根目录），并在 .settings.php 中设置 'composer' => ['value' => ['config_path' => '../composer.json']]；内核会引入其 vendor/autoload.php。
• bitrix.php（Symfony Console）需要它 — bitrix-console-commands。
• 切勿将包安装到 /bitrix/ 中。

文件优先级

• 组件、站点模板、php_interface 文件、.settings*.php：优先使用 /local/，然后是 /bitrix/。
• 组件模板：站点模板中的 components/… 会覆盖组件自身的 templates/。
• 模块：两者都存在时，/local/modules/<id> 优先。
• 模块路由不会自动加载：从 /local/routes/web.php 中 require 它们（bitrix-routing）。