如何在Laravel中部署phpDocumentor文档并实现授权访问与CI/CD更新

算力阿峰

2026-9-25

方案1：通过Laravel路由代理静态文档（无需修改phpDocumentor生成内容，推荐）

该方案完全不需要改动phpDocumentor生成的静态文件，完美适配CI/CD自动更新的场景，实现成本最低：

第一步：配置CI/CD流程，将生成的phpDocumentor静态文件上传到Laravel项目的非公开目录，比如storage/app/phpdoc，不要放在public目录下，避免静态文件被直接未授权访问。
第二步：准备授权逻辑，使用Laravel自带的auth中间件即可实现登录校验，如需更细粒度的权限控制，可以自定义Gate规则，比如view-api-docs权限。
第三步：在routes/web.php中添加文档路由，所有文档请求先经过授权校验，再返回对应静态文件：

use Illuminate\Support\Str;

Route::get('/docs/{path?}', function ($path = 'index.html') {
    // 校验路径合法性，防止目录穿越攻击
    $fullPath = realpath(storage_path("app/phpdoc/{$path}"));
    if (!$fullPath || !Str::startsWith($fullPath, storage_path('app/phpdoc'))) {
        abort(404);
    }
    // 自动识别mime类型返回响应
    return response()->file($fullPath);
})->where('path', '.*')->middleware('auth');

第四步：CI/CD流程无需做额外调整，每次生成文档后直接覆盖storage/app/phpdoc目录下的内容即可生效。

方案2：自定义phpDocumentor模板（仅适用于需要在文档中嵌入动态内容的场景）

如果确实需要修改默认生成的文档结构，可以按照以下步骤自定义模板，不需要完全重写，可继承官方默认模板做局部修改：

首先找到composer安装的phpDocumentor默认模板，路径为vendor/phpdocumentor/phpdocumentor/data/templates/default/，将该目录下的所有文件复制到你项目的自定义模板目录，比如phpdoc-templates/custom。
修改自定义模板目录下的template.xml，配置模板继承关系，避免重写全量模板代码：

<?xml version="1.0" encoding="utf-8"?>
<template>
  <name>custom</name>
  <version>1.0.0</version>
  <extends>default</extends>
</template>

所有页面结构都基于Twig模板实现，需要修改对应页面的话直接调整对应twig文件即可，比如要给所有页面加统一的头部逻辑，修改layout.html.twig即可。
生成文档时指定自定义模板路径即可：phpdoc run --template ./phpdoc-templates/custom

注意事项

优先选择方案1，该方案和phpDocumentor生成逻辑完全解耦，后续升级phpDocumentor版本或者更换文档生成工具都不需要调整授权逻辑，更符合CI/CD自动化的要求。

内容的提问来源于stack exchange，提问作者hereForLearing