PRISM部署保姆级教程:5步发布到GitHub Pages,含nojekyll坑与Cloudflare Pages方案
PRISM部署保姆级教程:5步发布到GitHub Pages,含nojekyll坑与Cloudflare Pages方案
PRISM(Portfolio & Research Interface Site Maker)是一款基于 Next.js 的免费学术个人主页构建工具,只需修改 TOML 和 Markdown 文件,就能生成包含论文、新闻、简历的精美主页。本文是一份零基础的 PRISM 部署教程:带你 5 步完成 GitHub Pages 静态站点发布,详解 .nojekyll 这个最常见的新手坑,并附赠 Cloudflare Pages 备选方案,帮你快速上线学术主页。
🎯 部署前准备:克隆 PRISM 并构建
PRISM 的输出是纯静态文件,部署前需要先在本地构建。完整配置说明可参考 README.md。
1️⃣ 安装环境
- 手动下载安装 Node.js 22+(package.json 中要求
node >= 22.0.0),不建议用系统自带的旧版本。 - 安装任意一个包管理器:npm / pnpm / yarn。
2️⃣ 克隆并构建
git clone https://gitcode.com/gh_mirrors/prism68/PRISM
cd PRISM
npm install
npm run build
构建成功后,项目根目录会多出一个 out/ 文件夹——里面就是你网站的全部静态文件,后续部署只需要它。
🚀 GitHub Pages 发布:5步走完全流程
官方中文部署指南见 docs/deployment_cn.md,英文原版见 docs/deployment.md。
第1步:创建 username.github.io 仓库
登录 GitHub,新建一个 Public 公开仓库,仓库名必须是 你的用户名.github.io(把用户名换成你的真实 GitHub 账号名)。这样你的网站才能绑定到根域名。
第2步:上传 out 目录内容
在仓库页面点击 "Upload files",把 out 文件夹里面所有文件(注意是里面的内容,不是文件夹本身)拖进去上传。
第3步:添加 .nojekyll 文件(最常见的坑!)
这是新手翻车率最高的一步。在仓库页面点击 Add file → Create new file,文件名填 .nojekyll(开头有个点、全小写),内容留空,直接 Commit。
⚠️ 为什么必须加?GitHub Pages 内置 Jekyll 引擎,会自动删除以下划线
_开头的文件夹,而 Next.js 静态导出的资源目录_next正是以下划线开头。不加这个文件,_next会被删掉,导致页面样式全部加载失败、白屏。
第4步:开启 Pages
进入仓库 Settings → Pages,在 Build and deployment 下确认来源为 "Deploy from a branch",选择 main 分支,点击 Save。
第5步:验收上线
稍等片刻,访问 https://你的用户名.github.io,你的学术主页就正式发布了 🎉
⚙️ 进阶:用 GitHub Actions 自动部署
手动上传每次改内容都要重复操作,仓库其实内置了 CI 工作流 .github/workflows/deploy.yml,可以每次 push 后自动构建并部署:
- Settings → Pages → Source 选择 GitHub Actions;
- 到 Actions 标签页,找到 "Deploy PRISM to GitHub Pages",点击 Enable workflow;
- 用 Run workflow 手动触发一次即可生效;
- (可选)想让每次 push 自动部署,编辑
deploy.yml并取消注释on: push配置。
子目录部署注意:如果仓库名不是 username.github.io,站点地址会变成 https://用户名.github.io/仓库名/,此时需要修改 next.config.ts,给资源加上路径前缀:
basePath: "/my-repo",
assetPrefix: "/my-repo",
☁️ 方案二:Cloudflare Pages(免 nojekyll 烦恼)
如果你不熟悉 GitHub Pages,或者想换个更快的 CDN,Cloudflare Pages 同样只需上传 out 文件夹,且完全没有 _next 被删的问题:
- 先执行
npm run build生成out/; - 登录 Cloudflare 控制台,进入 Workers & Pages → Create Application → Pages 标签页;
- 点击 Drag and drop your files,填写 Project name(将成为子域名前缀,如
my-site); - 把
out文件夹拖入上传区,点击 Deploy。
完成后网站即可通过 https://你的项目名.pages.dev 访问。
❓ 常见问题速查
| 问题 | 原因与解决 |
|---|---|
| 页面能打开但样式全乱/白屏 | 忘了加 .nojekyll,或上传时漏了 _next 目录 |
构建报错 Unsupported engine |
Node 版本低于 22,请手动升级 Node.js |
| 子仓库部署后 404 | 未设置 basePath 和 assetPrefix |
| 本地预览效果 | 运行 npm run dev,访问 http://localhost:3000 |
✨ 写在最后
部署完成后,就可以开始"装修"你的主页了:站点全局配置在 content/config.toml,论文列表由 content/publications.bib 直接驱动,还内置了 content_zh/ 多语言目录支持中英文双语切换。祝你的学术主页早日上线!

