使用 gh-pages 将 next.js15 静态项目部署到 github pages本文介绍了如何通过 gh-pag

以下我使用 next.js15 写的 Todo List 为例，假设我们本地已经存在一个 next.js15 的 Todo List 项目。

说明：解决了项目部署到 github pages 后访问不到 css、js、字体以及访问不到 public 目录下的图片问题。

第一步

安装 gh-pages：

npm i gh-pages

第二步

在 public 目录下新建一个 .nojekyll 的空文件。 这个空文件的作用是让 github 不要忽略以下划线开头的文件或文件夹，因为项目打包后会生成一个 _next 文件夹，如果没有 .nojekyll 文件，github 会忽略掉打包生成的 _next 文件夹，会导致部署后访问不到 CSS、字体等资源。

第三步

在next.config.ts 文件中添加以下配置。 因为我们要生成的是静态项目，所以要启用静态导出，这样在执行打包命令后，才能够得到一个 out 目录来进行部署到 github pages；因为我们的项目都是部署在自己 github 的一个子域下，所以 basePath 要设置为 github 项目名，由于我的 package.json 中 name 属性值与 github 上定义的项目名一致，所以这里我是直接从 package.json 中获取的。这里还通过 env 导出了一个环境变量，只是给页面中的 <Image /> 组件用的，因为官方提供的 <Image /> 组件在开发环境下可以直接通过相对路径访问到 public/ 目录下的图片，但是部署上去之后路径就不对了，所以这里提供一个环境变量，让 <Image /> 标签可以进行拼接使用。

import type { NextConfig } from 'next'

import { name } from './package.json'

// 基础路径
const NEXT_PUBLIC_BASE_PATH = process.env.NODE_ENV === 'production' ? `/${name}` : ''

const nextConfig: NextConfig = {
  output: 'export', // 启用静态导出
  basePath: NEXT_PUBLIC_BASE_PATH,
  env: {
    NEXT_PUBLIC_BASE_PATH
  }
}

export default nextConfig

第四步

进入 package.json 文件，在 "scripts" 中添加以下部署的脚本命令。 这里的 --dotfile 作用是让 ph-pages 部署时把我们刚刚创建的以点开头的文件 .nojekyll 也一并提交部署上去，不然它就会自动忽略掉这个问题，我们刚刚已经说了这个文件是有用的，要是不提交上去会导致部署事变。

  "scripts": {
    "deploy": "next build && gh-pages -d out --dotfiles"
  },

第五步

进入src/app/page.tsx，给 <Image /> 添加process.env.NEXT_PUBLIC_BASE_PATH基础路径。 这个步骤的作用是让图片资源在部署之后也可以正常访问到，否则就会出现开发环境能够访问，部署后访问不到图片的问题。

'use client'
import Image from 'next/image'
export default function Home() {
  
  return (
       <Image className='mr-1' src={`${process.env.NEXT_PUBLIC_BASE_PATH}/todo.svg`} alt='todo' width={25} height={25} />
  )
}

第六步

github 上创建一个react19-nextjs-todo-list仓库，并通过以下命令将提交代码到 github 上。 其中 xxx 是你自己的 github 账号名称。

git remote add origin https://github.com/xxx/react19-nextjs-todo-list.git
git branch -M main
git push -u origin main

第七步

执行部署命令，等待2分钟左右部署完成。

npm run deploy

在 github 的 Settings -> pages 中可以看到部署后的网站地址。 在这里插入图片描述 点击链接访问网站。