PHPStan 错误详解：nullableType.never —— 为什么 `?never` 是非法的可空类型声明及其正确修法

开发工具代码质量静态分析【免费下载链接】phpstanPHP Static Analysis Tool - discover bugs in your code without running it!项目地址https://gitcode.com/gh_mirrors/ph/phpstan点击查看免费下载本篇指南聚焦 PHPStanPHP 静态分析工具的错误标识nullableType.never完整讲解该错误在什么代码模式下被触发、PHP 语言层面为什么禁止?never这种写法以及两种经过源码验证的标准修复路径。读完本文你将能够准确识别并消除代码库中非法的可空never返回类型声明同时掌握never与void在语义上的本质区别避免在异常路径与正常返回路径之间混淆类型意图。错误标识速览该文档位于本仓库 website/errors/nullableType.never.md是 PHPStan 官方错误标识文档体系website/errors/中的一员。其元信息如下Frontmatter 字段值titlenullableType.nevershortDescriptionType never cannot be part of a nullable type declaration.never类型不能作为可空类型声明的一部分ignorablefalseignorable: false意味着这是一个不可忽略的硬错误无论你是否在配置中开启reportUnmatchedIgnoredErrors之外的宽松选项PHPStan 都会报告它因为它属于规则链中通过-nonIgnorable()标记的类型详见 website/errors/CLAUDE.md 对 frontmatter 的约定。换言之遇到这个错误唯一正确的出路就是修改代码而不是往ignoreErrors里添加条目。触发场景最小复现示例在任意被 PHPStan 分析的 PHP 文件中声明一个返回类型为?never的方法或函数即可触发?php declare(strict_types 1); class Foo { public function bar(string $a): ?never // error: Type never cannot be part of a nullable type declaration. { throw new \RuntimeException($a); } }运行 PHPStan 分析该文件时你会看到类似如下的报告Line: 4 Class Foo Type never cannot be part of a nullable type declaration. identifier: nullableType.never注意错误信息中携带的identifier: nullableType.never正是本文讨论的标识它可以用于ignoreErrors中的identifier:精确匹配也可以用于 CI 输出解析和 PHPStan Playground 的错误归类。为什么 PHPStan 会报告这个错误语言语义never与可空是矛盾的never返回类型表示一个函数永远不会正常返回——它要么总是抛出异常要么总是终止程序执行如调用exit/die。这是 PHP 8.1 引入的类型用于表达控制流不会走到函数末尾这一不变量。而可空修饰符?的含义恰恰相反?never意味着该函数可以返回null。一旦函数能够返回null它就确实返回了这与never的核心语义永不返回直接冲突。因此PHP 语言层面不允许never出现在可空类型声明?never中PHP 同样不允许never出现在联合类型声明中例如never|null、never|void都是非法的。换句话说?never是一个语法上无法表达、语义上自相矛盾的声明PHP 编译器会直接拒绝而 PHPStan 会以静态分析规则的形式在扫描阶段提前为你指出这一点。源码证据该错误来自 InvalidTypesInUnionRule从本仓库的标识注册表 website/src/errorsIdentifiers.json 可以看到nullableType.never由PHPStan\Rules\Types\InvalidTypesInUnionRule规则产出该规则在 phpstan-src 仓库 2.3.x 分支的src/Rules/Types/InvalidTypesInUnionRule.php第 117 行附近实现。同一个规则族还负责检查其他非法可空类型错误标识触发代码语义原因nullableType.never?nevernever永不返回与可空矛盾nullableType.void?voidvoid表示不返回任何值可空无意义nullableType.mixed?mixedmixed本身已包含null可空冗余这三个标识的详细文档分别见 nullableType.never.md、nullableType.void.md 和 nullableType.mixed.md它们共同构成了 PHPStan 对可空类型修饰符误用的完整检查面。从源码结构看InvalidTypesInUnionRule的职责就是集中校验类型声明中不允许出现在可空/联合位置的特殊类型never、void、mixed等从而把 PHP 编译器层面的类型合法性约束提前纳入静态分析流程。如何修复修复nullableType.never的关键是回答一个问题这个函数到底是永远不返回还是可能返回null答案决定你该选择哪种修复方案。方案一函数确实永不返回 → 去掉可空修饰符使用never如果函数体无条件抛出异常、调用exit或进入死循环函数确实永远不会正常返回那么never就是正确的类型只需删除?class Foo { - public function bar(string $a): ?never public function bar(string $a): never { throw new \RuntimeException($a); } }这样写不仅合法还向 PHPStan 和读者传达了最强的不变量调用bar()之后控制流绝不会继续往下执行。PHPStan 会在控制流分析中利用这一信息例如判断bar()之后的代码为不可达代码。方案二函数可能返回null→ 放弃never改用void或具体类型如果函数实际上有正常返回路径例如条件不满足时只是什么都不返回那么它根本不是never的语义应当改用void——void表示函数不返回任何有意义的值class Foo { - public function bar(string $a): ?never public function bar(string $a): void { if ($a ) { throw new \RuntimeException(Empty string); } } }这里void的语义是函数可以正常结束、不返回任何值也可以在特定分支抛出异常。这与函数实际行为完全吻合——不再存在返回null的说法因此根本不需要可空修饰符。如果你的业务场景确实是返回一个值但允许为null那么请使用真实的值类型例如?int、?string、string|null或mixed而不是试图用?never表达。补充PHP 8.1 以下版本的 PHPDoc 等价写法需要说明的是never原生类型声明要求 PHP 8.1。如果你需要兼容更低版本的 PHP 运行时例如项目以 PHP 7.4 为目标可以使用 PHPDoc 标签return never达到相同的静态分析效果让 PHPStan 依然能识别此函数永不返回/** * return never */ public function bar(string $a) { throw new \RuntimeException($a); }PHPDoc 中的never、联合类型、交叉类型等写法均不依赖运行时版本PHPStan 会基于 PHPDoc 进行等价分析。这一点与同目录下其他错误文档如 nullableType.void.md给出的处理原则一致当错误涉及仅在更新 PHP 版本中可用的语言特性时优先提示 PHPDoc 替代方案。排查实践建议先问语义再改类型遇到nullableType.never先判断函数是否有正常返回路径。有 →void或具体类型没有 → 保留never。警惕吞掉异常式的重构把?never改成void后注意函数体末尾若缺少throw/exit控制流会自然落空返回这是合法的void行为但要确认业务上是否符合预期。利用标识做 CI 治理由于nullableType.never的ignorable: false无法通过ignoreErrors压制在团队 CI 中可以通过解析identifier: nullableType.never统计这类类型声明误用推动代码规范落地。善用 Playground 快速验证可以把最小复现片段粘贴到 PHPStan Playground本项目提供 playground-api 与 playground-runner 两套实现配合目标 PHP 版本快速确认修复后的代码不再报错。小结nullableType.never是 PHPStan 对 PHP 类型系统约束的静态化表达never的永不返回语义与?的可为 null语义天然互斥因此?never在任何情况下都不是合法声明。修复的核心在于还原函数真实意图——永不返回用never不返回值用void可能返回null用真实值类型加可空修饰。理解并善用这一规则能让你在异常路径与正常返回路径之间写出类型意图清晰、经得起静态分析检验的 PHP 代码。赞分享开发工具代码质量静态分析【免费下载链接】phpstanPHP Static Analysis Tool - discover bugs in your code without running it!项目地址https://gitcode.com/gh_mirrors/ph/phpstan点击查看免费下载相关推荐PHPStan 错误详解nullableType.void —— 为什么 ?void 是非法的可空返回类型PHPStan 错误详解nullableType.void —— 为什么 ?void 是非法的可空返回类型 本指南聚焦 PHPStan 的 nullableT开发工具代码质量静态分析PHPStan method.abstractPrivate 错误解析抽象方法为何不能声明为 private以及正确的修复方案PHPStan method.abstractPrivate 错误解析抽象方法为何不能声明为 private以及正确的修复方案 在 PHP 语言中 abs开发工具代码质量静态分析PHPStan return.never 错误标识符详解修复 never 返回类型函数中的非法 return 语句PHPStan return.never 错误标识符详解修复 never 返回类型函数中的非法 return 语句 本文聚焦 PHPStan 错误标识符 re开发工具代码质量静态分析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考