Strapi Swagger插件部署GCP App Engine后访问文档返回404问题咨询

问题根因 #

GCP App Engine 标准实例的运行时文件系统为只读模式，仅/tmp目录允许写入操作。你遇到的报错是因为Strapi的Swagger插件默认会在服务启动时尝试重新生成文档文件并写入/workspace/extensions/documentation/public/路径，触发了只读文件系统权限限制。即使本地已提前生成文档，只要生产环境启动时插件触发了写入逻辑就会报错，进而导致页面404。

解决步骤 #

1. 关闭生产环境启动自动生成文档逻辑
   在项目config/env/production/plugins.js（无该文件则新建）中添加如下配置，禁止插件在生产环境启动时重新生成文档：

module.exports = {
  documentation: {
    enabled: true,
    config: {
      autoGenerate: false,
    }
  }
};

2. 本地预生成文档并纳入部署文件
   本地启动Strapi服务，访问一次文档页面触发完整的文档生成流程，确认extensions/documentation/public/目录下已生成对应版本的文档文件。检查项目.gitignore和.gcloudignore文件，确保该目录没有被忽略，部署时会被同步上传到App Engine。
3. 可选：构建阶段自动生成文档
   如果你不想手动本地生成，可以在package.json的build脚本中加入文档生成逻辑，App Engine部署阶段的构建环节拥有写入权限，会提前生成好文档文件：

{
  "scripts": {
    "build": "strapi build && node -e \"require('strapi-plugin-documentation/services/documentation').generateDoc()\""
  }
}

4. 验证部署配置
   确认你的app.yaml中没有额外的路由规则拦截/documentation路径的静态资源请求，配置示例参考：

runtime: nodejs14
service: strapi-service
env: standard
instance_class: F2
handlers:
  - url: /(.*\.(gif|png|jpg|css|js|html))$
    static_files: public/\1
    upload: public/.*
  - url: /.*
    secure: always
    script: auto

完成以上配置后重新部署即可正常访问文档页面。

内容的提问来源于stack exchange，提问作者Juan Sebastián González