Next.js项目pa11y-ci本地正常但Github Actions CI连接localhost失败

我的Pa11y-CI测试在本地运行正常，但在GitHub Actions CI环境中执行失败，表现为无法连接localhost:3000。以下是相关配置和错误信息：

相关配置 #

.pa11yci.json配置 #

{
  "defaults": {
    "timeout": 60000
  },
  "urls": [
    {
      "url": "http://localhost:3000",
      "viewport": { "width": 320, "height": 480 },
      "actions": [
        "wait for element #main-content to be visible",
        "screen capture screenshots-output/mobile-main-view.png",
        "click element .usa-navbar button",
        "screen capture screenshots-output/mobile-expand-menu.png"
      ]
    },
    {
      "url": "http://localhost:3000",
      "actions": [
        "wait for element #main-content to be visible",
        "screen capture screenshots-output/desktop-main-view-home.png"
      ]
    }
  ]
}

package.json中的scripts配置 #

"scripts": {
  ...
  "test:pa11y": "pa11y-ci --config .pa11yci.json",
  ...
}

GitHub Actions工作流文件ci-frontend-a11y.yml配置 #

name: pa11y tests

on:
  pull_request:
    paths:
      - frontend/**
      - .github/workflows/ci-frontend-a11y.yml

jobs:
  build:
    name: Pa11y-ci tests
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: ./frontend

    env:
      NODE_VERSION: 20
      LOCKFILE_PATH: ./frontend/package-lock.json
      PACKAGE_MANAGER: npm

    steps:
      - name: Checkout source
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache-dependency-path: ${{ env.LOCKFILE_PATH }}
          cache: ${{ env.PACKAGE_MANAGER }}

      - name: Install dependencies
        run: npm ci

      - name: Create screenshots directory
        run: mkdir -p screenshots-output

      - name: Build project
        run: npm run build

      - name: Start server and log output
        run: npm run start &

      - name: Wait for server to be ready
        run: |
          # Ensure the server wait script is executable
          chmod +x ./bin/wait-for-frontend.sh
          ./bin/wait-for-frontend.sh

      - name: Run pa11y-ci
        run: |
            npm run test:pa11y
            echo "pa11y-ci tests finished."

等待服务的脚本 #

我有一个用于等待localhost:3000可用的shell脚本./bin/wait-for-frontend.sh。

CI执行错误日志 #

Run npm run test:pa11y
  npm run test:pa11y
  echo "pa11y-ci tests finished."
  shell: /usr/bin/bash -e {0}
  env:
    NODE_VERSION: 20
    LOCKFILE_PATH: ./frontend/package-lock.json
    PACKAGE_MANAGER: npm

> frontend@0.1.0 test:pa11y
> pa11y-ci --config .pa11yci.json

Running Pa11y on 10 URLs:
 > http://localhost:3000/ - Failed to run
pa11y-ci tests finished.

排查与解决方案 #

1. 替换等待脚本为可靠检测逻辑 #

原等待脚本可能未正确识别服务就绪状态，替换为基于curl的循环检测脚本：

#!/bin/bash
MAX_RETRIES=30
RETRY_INTERVAL=2
RETRIES=0

until curl -s http://localhost:3000 > /dev/null || [ $RETRIES -eq $MAX_RETRIES ]; do
  echo "Waiting for server to start... ($RETRIES/$MAX_RETRIES)"
  sleep $RETRY_INTERVAL
  RETRIES=$((RETRIES+1))
done

if [ $RETRIES -eq $MAX_RETRIES ]; then
  echo "Server did not start within timeout period"
  exit 1
fi

2. 验证服务启动状态 #

在CI流程中添加端口检测步骤，确认服务是否实际运行：

- name: Check if server is listening on port 3000
  run: lsof -i :3000 || netstat -tulpn | grep 3000 || ss -tulpn | grep 3000

3. 调整Pa11y超时配置 #

在.pa11yci.json中增加全局等待时长，确保页面有足够时间加载：

{
  "defaults": {
    "timeout": 60000,
    "wait": 10000
  },
  "urls": [
    // 原有URL配置
  ]
}

4. 排查端口占用问题 #

GitHub Actions虚拟机可能存在端口冲突，尝试修改服务启动端口为其他值（如3001），同步更新Pa11y配置中的URL和等待脚本的端口。

5. 捕获服务启动日志 #

修改服务启动步骤，将日志输出到文件用于调试：

- name: Start server and log output
  run: npm run start > server.log 2>&1 &
- name: Show server logs (debug)
  run: cat server.log

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