src/和tests/必须平级分离，命名空间须与composer.json的name字段严格对齐，如linxi/exception-helper对应LinxiExceptionHelper；autoload-dev需配置tests/映射，type和extra须按企业场景准确填写。
src/ 和 tests/ 必须分离，且命名空间要与 vendor-name/package-name 严格对齐
包内 src/ 下的 PHP 类，其命名空间前缀必须和 composer.json 中的 name 字段一致。比如包名是 linxi/exception-helper，那核心类就该放在 src/ExceptionHelper.php，命名空间必须是 LinxiExceptionHelper（注意大小写），不能是 AppExceptionHelper 或 ExceptionHelper。Composer 的 PSR-4 自动加载靠这个映射定位文件，错一个字母都找不到类。
测试目录 tests/ 要和 src/ 平级，且 PHPUnit 配置里 autoload-dev 的 PSR-4 映射也得对应上，例如：
{"autoload-dev": {"psr-4": {"Linxi\ExceptionHelper\Tests\": "tests/"}}
常见错误现象：Class 'LinxiExceptionHelperTestsTestCase' not found，往往是因为 tests/ 下文件的命名空间漏了 Tests 子段，或 composer.json 里没配 autoload-dev。
composer.json 的 type、autoload 和 extra 必须按企业场景填准
企业包不是玩具项目，type 字段不能留空或填 library 就完事。如果包提供 Laravel Service Provider，应设为 laravel-package；如果是通用命令行工具，用 project 或自定义 php-cli-tool；若含 Artisan 命令或配置发布逻辑，extra 里得明确声明 laravel 配置项，例如：
"extra": { "laravel": { "providers": ["Linxi\ExceptionHelper\ExceptionHelperProvider"] } }
autoload 段必须只包含生产必需路径，autoload-dev 才放测试和示例代码。别把 examples/ 或 docs/ 加进主 autoload —— 这会导致用户安装后无谓加载一堆不使用的类，影响性能。
容易踩的坑：在 autoload 里写 "": "src/"（即空前缀），这会让所有类暴露在全局命名空间，破坏封装性，也违反 PSR-4 最佳实践。
provider 和 config 文件要可选发布，不能硬编码路径
服务提供者（如 ExceptionHelperProvider）必须放在 src/ 下，但它的注册逻辑要能区分“是否在 Laravel 环境中”。不能直接 $this->app->bind() 就完事，得加运行时判断：
public function register() { if ($this->app instanceof Application && class_exists(Application::class)) { $this->app->bind('exception.helper', function () { return new Helper(); }); } }
配置文件（如 config/exception-helper.php）不能直接 require 进 provider，而应通过 publishes() 方法提供可选发布能力，并在 composer.json 的 extra 里声明路径映射：
"extra": { "laravel": { "providers": [...], "aliases": {...}, "config": ["config/exception-helper.php"] } }
否则下游项目调用 php artisan vendor:publish 时根本找不到你的配置，强行复制粘贴又难维护版本升级。
不要在包里写 vendor/ 或试图绕过 Composer 的路径规则
有人想“让包自己管理依赖”，于是在 src/ 里手动 require 'vendor/autoload.php'，这是危险操作。Composer 包必须信任宿主项目的自动加载机制，绝不能引入第二套 vendor/ 或嵌套 composer install。所有依赖都应在 composer.json 的 require 字段声明，由宿主项目统一解析和安装。
同理，别在包代码里硬写 __DIR__ . '/../../vendor' 这类路径——vendor 目录位置可能被全局 config.json 改写，也可能被 symlinks 替代，运行时不可靠。要用 Composer 提供的标准方式获取资源，比如通过 Package::getInstallPath()（需监听事件）或约定相对路径读取 config/ 下的文件。
最常被忽略的一点：企业包一旦发布到私有源，它的 name 字段就固化了。改名=新包，旧项目不会自动迁移。所以一开始就要想清楚 vendor-name 是用公司域名反写（com-mycompany）、GitHub 用户名（mycompany），还是统一前缀（myorg），之后很难回头。
