Next.js在GitHub Actions构建失败：Google Fonts获取异常

在GitHub Actions中构建Next.js项目时，构建过程在获取Google Fonts时卡住数分钟，有时直接失败。错误日志如下：

#12 10.13    Creating an optimized production build ...
#12 52.98 request to https://fonts.gstatic.com/s/ubuntu/v20/4iCv6KVjbNBYlgoC1CzjvWyNPYZvg7UI.woff2 failed, reason: 
#12 52.98 
#12 52.98 Retrying 1/3...
#12 52.99 request to https://fonts.gstatic.com/s/ubuntu/v20/4iCv6KVjbNBYlgoC1CzjtGyNPYZvg7UI.woff2 failed, reason: 
#12 52.99 
#12 52.99 Retrying 1/3...
#12 52.99 request to https://fonts.gstatic.com/s/ubuntu/v20/4iCv6KVjbNBYlgoC1CzjvGyNPYZvg7UI.woff2 failed, reason: 
#12 52.99 
#12 52.99 Retrying 1/3...
#12 53.00 request to https://fonts.gstatic.com/s/ubuntu/v20/4iCv6KVjbNBYlgoC1Czjs2yNPYZvg7UI.woff2 failed, reason: 
#12 53.00 
#12 53.00 Retrying 1/3...
#12 53.01 request to https://fonts.gstatic.com/s/ubuntu/v20/4iCv6KVjbNBYlgoC1CzjvmyNPYZvg7UI.woff2 failed, reason: 
#12 53.01 
#12 53.01 Retrying 1/3...
#12 53.01 request to https://fonts.gstatic.com/s/ubuntu/v20/4iCv6KVjbNBYlgoC1CzjsGyNPYZvgw.woff2 failed, reason: 
#12 53.01 
#12 53.01 Retrying 1/3...
#12 53.02 request to https://fonts.gstatic.com/s/ubuntu/v20/4iCs6KVjbNBYlgoKew72nU6AF7xm.woff2 failed, reason: 
.
.
.

构建会多次重试，部分场景下7分钟后能成功，但偶尔会因无法获取字体直接失败。本地构建完全正常。

项目中导入字体的代码如下：

import "../styles/globals.css";
import "../styles/Main.scss";
import Head from "./head";
import NextAuthSessionProvider from "./SessionProvider";
import { Oswald, Ubuntu, Play } from 'next/font/google';

const oswald = Oswald({ subsets: ['latin'] });
const ubuntu = Ubuntu({ weight: ['300', '400', '500', '700'], subsets: ['latin'] });
const play = Play({ weight: ['400', '700'], subsets: ['latin'] });

export default function RootLayout({ children }) {
  return (
    <html lang="en" className={`${oswald.className} ${ubuntu.className} ${play.className}`}>
      <Head />
      <body>
        <NextAuthSessionProvider>
          {children}
        </NextAuthSessionProvider>
      </body>
    </html>
  );
}

预下载字体到本地，彻底规避远程请求 #

1. 手动下载所需字体文件（Oswald、Ubuntu、Play的对应权重和子集），放置到项目的public/fonts目录下。
2. 改用next/font/local导入本地字体，替换原有的next/font/google：

   import { Oswald, Ubuntu, Play } from 'next/font/local';
   
   const oswald = Oswald({
     src: './fonts/Oswald-Regular.ttf', // 对应本地文件路径
     subsets: ['latin'],
   });
   
   const ubuntu = Ubuntu({
     src: [
       {
         path: './fonts/Ubuntu-Light.ttf',
         weight: '300',
       },
       {
         path: './fonts/Ubuntu-Regular.ttf',
         weight: '400',
       },
       {
         path: './fonts/Ubuntu-Medium.ttf',
         weight: '500',
       },
       {
         path: './fonts/Ubuntu-Bold.ttf',
         weight: '700',
       },
     ],
     subsets: ['latin'],
   });
   
   const play = Play({
     src: [
       {
         path: './fonts/Play-Regular.ttf',
         weight: '400',
       },
       {
         path: './fonts/Play-Bold.ttf',
         weight: '700',
       },
     ],
     subsets: ['latin'],
   });
   

启用GitHub Actions构建缓存，复用已下载字体 #

1. 在next.config.js中开启字体缓存配置：

   /** @type {import('next').NextConfig} */
   const nextConfig = {
     experimental: {
       fontLoaders: [
         { loader: 'next/font/google', options: { subsets: ['latin'] } },
       ],
     },
     caching: {
       fonts: true,
     },
   };
   
   module.exports = nextConfig;
   

2. 在GitHub Actions工作流文件中添加缓存步骤：

   - name: Cache Next.js build
     uses: actions/cache@v3
     with:
       path: |
         .next/cache
       key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/*.js', '**/*.ts', '**/*.tsx') }}
       restore-keys: |
         ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-
   

调整字体请求超时设置，避免无限重试 #

在next.config.js中配置字体请求的超时时间，减少等待时长：

const nextConfig = {
  experimental: {
    fontLoaders: [
      { 
        loader: 'next/font/google', 
        options: { 
          subsets: ['latin'],
          timeout: 5000, // 设置5秒超时，超时后终止请求
        } 
      },
    ],
  },
};

module.exports = nextConfig;

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