常见问题

装配、迁移与日常使用里最容易卡住的地方，逐条给结论，并指到对应参考页。

定位

本页只回答「为什么这样设计」「这一步该用哪个入口」这类判断题；具体签名与参数表看对应的参考页，升级细节看2.0 迁移说明。

装配

内核里为什么没有容器和路由

风音框架只提供辅助能力。Kernel 持有配置、日志、翻译器、HTTP 客户端与接入方适配器，不解析路由、不做依赖注入、不接管请求生命周期。容器与路由属于宿主框架，需要互通时用 Fxri\Integration\ThinkPHP\ThinkPHPAdapter 把内核绑进容器，见接入已有框架。

不传任何装配项可以直接构建吗

可以。KernelBuilder::make()->build() 是合法用法：配置为空 Config，日志为 NullLogger，翻译器为内置 ArrayTranslator，httpClient() 与 adapter() 返回 null。按需注入即可，不必凑齐全部装配项。

多个配置目录谁覆盖谁

按 withConfigDir() 的追加顺序，后者覆盖前者；同一目录内按文件名排序加载，文件名为顶层键，文件返回非数组时视为该文件没有配置。嵌套数组是递归合并，不是整块替换，见配置。

怎么替换默认翻译器

withTranslator() 接受任意 Symfony\Contracts\Translation\TranslatorInterface 实现。内置的 ArrayTranslator::fromDirectory() 按目录加载「词条 => 译文」的 PHP 文件，未命中时返回词条本身而不是抛出异常。

配置项怎么读

$kernel->config()->get('app.name', '默认值')，点号表示层级；has() 判存在，all() 取全量。读取发生在运行期，构建内核后配置不再变动。

迁移

1.x 的门面和全局函数去哪了

2.0 移除了 tree / xml 等门面与全局函数，统一改成 Fxri\* 下的静态类与 Kernel 实例方法。逐项对照与替代写法见2.0 迁移说明。

原来的数字 type 参数怎么改

全部改为具名枚举或链式方法，例如文本处理用 FieldTextMode、UUID 用 UuidMode、时间粒度用 DateGranularity。旧的 1.1.2 这类点分模式号不再可用，composer scan 会拦截新增的数字枚举写法。

旧密文还能解密吗

能，仅解密：LegacyCipher::decrypt($payload, $password)。新数据一律用 Cipher::make($key) 加密，不要再用旧格式写新数据，见安全。

之前返回的六元响应数组呢

改为 Envelope 的固定四字段 ok / code / message / data，旧数组里的扩展位与时间位已移除。需要额外信息时放进 data，见HTTP。

使用

Fxri\Param 和 Fxri\Data\Param 有什么区别

Fxri\Param 是入参定义与整形：Definition、Shape、Pipeline、Merger、Picker，管「补默认值、定形状、按需挑选」。Fxri\Data\Param 只有两个数据整理方法：filter() 去掉空值，missing() 找出空值键。前者面向入口，后者面向整理，见参数与数据。

SQL 构造器会连接数据库执行吗

不会。WhereBuilder、StatementBuilder、MysqlDialect 只产出 Sql（SQL 片段加 bindings()），执行与事务交给调用方的 PDO 或 ORM，见SQL。

Responder::send() 会输出响应头吗

会按信封结果设置状态码与 Content-Type 并输出正文；如果响应头已经发出，则只输出正文。需要完全自定义响应头时，用 format() 取格式化后的字符串自行输出，见HTTP。

文档站的「更新日志」能直接改吗

不能。docs/changelog.md 由 pnpm sync:changelog-doc 从根 CHANGELOG.md 生成，页面内也注明了请勿手改；要改内容请改根文件后重新同步，见贡献指南。

一定要安装 PSR 相关包吗

不是。只有用到 Http\HttpClient\Client、ClientFactory 或 fromPsrRequest() 系列时才需要 psr/http-client、psr/http-message 等包；不安装也能使用其余能力，缺失时相关入口会明确报错，不会静默降级。

支持哪些 PHP 版本

PHP 8.2 起，CI 覆盖 8.2 至 8.5。mbstring 与 openssl 是必装扩展，其余依赖按需安装，见快速开始。

注意事项

• 本页描述的是当前 2.x 行为；历史版本的实际行为以更新日志中的归档条目为准。
• 若实际表现与本页或参考页不符，先跑一次 composer check 确认基线，再回查对应页的签名表，避免把环境差异当成框架缺陷。