scribe 双平台中文文档需统一 php utf-8 环境、配置 config/scribe.php 显式设为中文、用 phpdoc 注解定义分组与字段、替换 blade 模板中文本。
要在 Windows 和 macOS 双平台下稳定生成中文 API 文档，Scribe 配置必须兼顾环境一致性、编码兼容性和视图可控性——不是装完插件就完事，而是从 PHP 运行时、注释写法到 Blade 渲染层层对齐。
确保 PHP 环境支持 UTF-8 与中文路径
Scribe 解析控制器注释时依赖 PHP 的字符串处理能力，若系统 locale 或文件编码不统一，中文注释会乱码或被跳过：
- Windows：用 PowerShell 运行 chcp 65001 切换为 UTF-8 编码，再启动 artisan 命令；确认 php.ini 中 default_charset = "UTF-8"
- macOS：在 ~/.zshrc 中添加 export LANG=en_US.UTF-8（不推荐 zh_CN.UTF-8，部分扩展解析异常），重启终端后验证 locale 输出含 UTF-8
- 所有控制器文件保存为 UTF-8 无 BOM 格式（VS Code 默认即符合，Sublime/PhpStorm 需手动检查）
配置 Scribe 并统一中文元信息
config/scribe.php 是跨平台文档行为的中枢，需显式声明语言与结构，避免依赖系统 locale：
- 设置 'title' => 'XX项目API文档（中文版）'、'description' => '面向前端与第三方调用的接口说明'
- 指定 'default_language' => 'zh'，让示例代码块默认使用中文变量名（如
$data = [...]） - 关闭自动检测：将 'laravel_api_resources' => false（除非你真用了 Laravel Resource 类，否则易因 Windows/macOS 类加载顺序差异导致生成中断）
- 禁用缓存干扰：'cache' => ['enabled' => false]，避免 Windows 下 cache 文件权限残留影响 macOS 二次生成
用注解驱动中文分组与接口标题
中文标题不靠翻译文件，而靠控制器顶部的 PHPDoc 注解——Scribe 直接提取，双平台完全一致：
- 在控制器类开头写：@group 用户管理、@subgroup 登录与认证
- 在方法上方写：@responseField code int 返回码，200 表示成功、@bodyParam phone string required 手机号，11位数字
- 避免空格或特殊符号：如 @group 用户管理 不要写成 @group 用户 管理（空格会导致分组名截断）
- 所有注解用中文全角标点，Scribe v4+ 已原生支持，无需额外转义
发布并定制中文视图模板
默认 HTML 页面按钮仍是英文，必须替换视图——且要适配双平台文件系统行为：
- 运行 php artisan vendor:publish --tag=scribe-views，模板会复制到 resources/views/vendor/scribe
- 编辑 index.blade.php，直接替换原文本："Try it out" → "调试接口"、"Response body" → "响应数据"、"Send request" → "发送请求"
- Windows 用户注意：Blade 模板中不要用 __() 函数调用翻译，因 Laravel 的 lang/ 目录在 Windows 下可能因大小写或路径分隔符导致加载失败；macOS 虽支持，但为统一，全部写死中文更可靠
- 生成后检查 storage/docs/index.html 是否能用浏览器直接打开（无需 Web 服务器），验证中文显示正常
