Google Cloud Run首次部署遇404错误求助

问题诊断 #

你的核心问题是Koa后端未正确配置前端静态文件的服务逻辑，尤其是单页应用(SPA)的路由 fallback。本地正常是因为开发环境的dev server自动处理了SPA路由，而Cloud Run上的生产环境Koa服务没有对应的配置，导致访问根路径或前端路由时返回404，但API路由（如/api/data）不受影响。

解决方案 #

1. 确认静态文件目录的路径配置 #

检查Koa代码中koa-static中间件的路径是否正确。假设项目结构为：

project-root/
├── client/
│   └── build/  # Preact构建产物
└── server/
    └── index.js  # Koa后端代码

在Koa中需正确指向build目录，示例代码：

const serve = require('koa-static');
const path = require('path');
// 从server目录向上定位到client/build
app.use(serve(path.join(__dirname, '../client/build')));

部署时要确保client/build目录被正确包含在部署包或Docker镜像中，避免路径缺失。

2. 添加SPA路由Fallback配置 #

Preact作为单页应用，所有前端路由（包括根路径/）都需要返回index.html，否则刷新或直接访问路由时会触发服务器404。在Koa中添加以下中间件（放在静态文件中间件之后、API路由之前）：

const fs = require('fs');
const path = require('path');

// 拦截非API请求，返回前端入口文件
app.use(async (ctx, next) => {
  if (!ctx.path.startsWith('/api')) {
    const indexPath = path.join(__dirname, '../client/build/index.html');
    ctx.type = 'html';
    ctx.body = fs.readFileSync(indexPath);
  }
  await next();
});

该中间件会让所有非API请求返回index.html，交由Preact的前端路由接管页面渲染。

3. 检查部署配置 #

• 确保部署前已在client目录执行npm run build，生成完整的build目录
• 若直接用gcloud run deploy部署，确认项目根目录的package.json中start命令正确指向Koa服务入口，示例：

  "scripts": {
    "start": "node server/index.js"
  }
  

• 若使用Docker部署，确保Dockerfile中复制了前端构建产物，示例：

  # 构建前端
  FROM node:18-alpine as build-client
  WORKDIR /app/client
  COPY client/package*.json ./
  RUN npm install
  COPY client/ ./
  RUN npm run build
  
  # 构建后端镜像
  FROM node:18-alpine
  WORKDIR /app
  COPY server/package*.json ./
  RUN npm install
  COPY server/ ./
  # 复制前端构建产物到镜像
  COPY --from=build-client /app/client/build ./client/build
  CMD ["node", "server/index.js"]
  

验证步骤 #

1. 本地修改代码后，重新构建前端并启动后端，确认根路径和前端路由可正常访问
2. 重新部署到Cloud Run，等待部署完成后访问URL，检查404问题是否解决

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