📝 基地官网重构记录:从 Docusaurus 到 Next.js

📝 基地官网重构记录:从 Docusaurus 到 Next.js

📌 前言:为什么突然要重构

基地官网是 2020 年 5 月建的,那会儿用的是 Docusaurus 2.0-beta——一个专门做文档站的框架。六年下来,264 个 commit,中间在 2025 年 6 月升级过一次到 3.8.1,但整体架构一直没动。

真正让我下决心的是两件事凑到了一起。

第一件:技术债实在堆得有点多。 antd 还是 v4(官方早就停止维护了),TypeScript 配置写着 strict 但代码里全是隐式的 any,package-lock.json 和 yarn.lock 两个锁文件并存,moment 这种没写进依赖的”幽灵包”也在用。最离谱的是,全站其实只用了 antd 里的六七个组件,却背了整个 UI 库和它的 CSS。

第二件:内容早就跟现实脱节了。 官网首页写着”四大部门”,但我们早就合并成三大部门了;页脚写着 ©2003,实际基地是 2007 年建的。文档和博客在 2021 年之后就没更新过,属于”挂着但没人看”的状态。

至于为什么是这个时候——10.24 程序员节那天,ZCode 送了一大笔 token 额度,不用白不用。本来估摸着要两周的活,结果两天就干完了。这篇文章记录整个过程,包括中间踩的坑。


🔍 第一步:先花一小时”考古”

动手之前我先做了一件很多人容易跳过的事:把基地的资料盘整个扫了一遍。

E:\A 创新基地 这个目录里有 33,922 个文件,从 2007 年的建基档案、历年大事记、招新考核记录,到 2026 年在做的招新物料都在里面。我让 AI 帮我按信息密度排了个优先级,重点读了这几类:

  • 2026 招新的宣讲 PPT、介绍 PPT(最新官方口径)
  • FTP 资料库的整理记录和规范文档
  • 2013–2022 的年份归档(大事记、获奖情况)

扫完的收获比预想大得多:

  • 官方口径早就变了:2026 的 PPT 里明确是「软件部 / 大数据部 / 算法部」三大部门九个方向,信息安全部已经撤销
  • 建基年份是 2007:两份 PPT 和年份归档都印证了,官网那个 ©2003 是错的
  • 家底比想象厚:FTP 里 11,455 份资料、132.7GB、八个分区,2026 年 9 月刚做完一次全库整理(修复了 1535 个坏文件名,零数据丢失)
  • 文案素材是现成的:宣讲 PPT 里的部门介绍、培养路径、招新流程,质量都比旧官网高

这一步让我意识到:这次重构不是”换个皮”,而是把官网的内容基础重新校准一遍。


👀 第二步:看一眼别人家的站

国内高校社团里,桂电三院科协的官网(hello.kexie.space)做得比较出名,我专门去研究了一下。

值得学的:

  • 长单页的信息组织——Hero → 部门 → 学习方向 → 招新时间线 → 荣誉 → 留言 → 项目展示,新生的阅读路径很完整
  • 生态入口意识——OJ、Git、知识库、QQ 群全挂在首页,官网不只是”介绍”,还是工具入口
  • 社区氛围——留言板从 2022 年一直有人留言到今年,这种”人气证明”对招新很有说服力

结论:长单页 + 资源统一入口这个思路要学,但技术路线走静态生成。


📊 第三步:技术选型与九个决策点

最后定的技术栈:

层 选择
框架 Next.js 15(静态导出,output: 'export')
语言 TypeScript(这回是真的 strict)
样式 Tailwind CSS v4
包管理 pnpm(单一锁文件)
3D three.js + @react-three/fiber
数据校验 zod
评论 Waline(自托管)

几个关键决策:

为什么不继续用 Docusaurus? 它是文档站框架,做展示型官网本身就有点错位。旧站的文档博客 2021 年后就没更新了,为了这两个板块继续背一个框架,不划算。

为什么不走三院那种 Vite SPA? 静态生成的产物首屏更快、SEO 更友好,而且部署到哪都行(我们的服务器、GitHub Pages、Cloudflare 都无所谓)。

内容怎么维护? 全部抽成 content/ 下的 JSON——成员、荣誉、部门介绍、站点配置。以后加一个成员、加一条荣誉,改 JSON 提 PR 就行,不用碰代码。

中途还定了另外几个点(旧站文档去留、评论系统选型、品牌色、托管方式、域名策略),一共九个决策,逐个拍板。这一步我觉得特别值:后面的所有代码都长在这些共识上,返工极少。


🧹 第四步:先把数据理干净

正式写页面前,先处理了三笔”历史遗留”。

荣誉数据的三处分叉

旧站的荣誉数据散在三个地方:页面组件里内联的一大坨数组、一个单独的 historicalHonor.data.ts 文件、还有一堆没提交的改动。三份内容互相不完全一样。

我把它们合并去重,还发现一条重复记录——「2023年全国高校计算机能力挑战赛」和「2023年第五届全国高校计算机能力挑战赛」其实是同一个比赛,只是名字一个写了全称一个没写。

FTP 编目页的 289 字节之谜

基地有个 FTP 资料库导航页,本地文件和线上部署版差了 289 字节。一开始以为是内容有差异,diff 下来发现内容逐行完全一致。

后来想明白了:

1
617,445 - 617,156 = 289

正好等于文件里 CRLF 换行符的数量(289 个)。部署的时候行尾被归一成 LF 了,实际内容一个字节都没差。本地文件就是唯一源头。

留言数据先备份

旧站的留言存在 GitHub Issue 里,一共 22 条,时间跨度从 2022 年 8 月到 2026 年 5 月。重构之前先把它们导出成 JSON 存好了——事实证明这一步非常明智,后面迁移全靠它。


🎨 第五步:3D 首页的 20 选 1

这是整个项目里最花时间、也最”好玩”的一部分。

我的要求很简单:首页要够酷,但不能挡住字。 于是让 AI 一口气做了二十个 three.js 场景候选:

粒子网络、深空星云、Logo 粒子汇聚、数学符号(π∑∫ 漂浮)、极光帘幕、正弦波场、网格星球、洛伦兹风暴眼(真的积分了洛伦兹吸引子)、超立方折光门(真四维旋转投影)、算法织机、向量场之茧(curl noise 流线)、日蚀磁场、黄金比例之门、分形算法林、量子棱镜潮汐、红移星环、镜面纪念碑、时间算法(浑天仪)……

第一轮从 20 个筛到 7 个,第二轮从 7 个筛到 1 个,最后定的是「时间算法」——把古代浑天仪重做成一台未来数学装置:四层倾斜轨道环、720 格刻度、几百颗沿轨飞行的光点,配上青铜绿和铜金的配色。

中间来回改了好几轮:

  • 性能:一开始用了 Bloom 后处理做辉光,结果全屏多通道模糊直接把帧率干下去了。后来去掉后处理,改用大尺寸柔边光晕粒子模拟辉光,帧率立刻回来
  • 速度:整体动效 2 倍速,沿轨粒子从 46 颗加到 368 颗
  • 配色:最开始是青铜绿×铜金,后来试了冰蓝×白,发现和页面其它部分更协调,就换成了冰蓝×白

顺手记一条经验:3D 特效一定要做分级质量 + 懒加载。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// 根据设备能力分三档
function detectTier() {
if (matchMedia("(prefers-reduced-motion: reduce)").matches) return "low";

const canvas = document.createElement("canvas");
const gl = canvas.getContext("webgl2") ?? canvas.getContext("webgl");
if (!gl) return "low"; // 不支持 WebGL → 静态渐变兜底

if (window.innerWidth < 768) return "medium"; // 移动端默认中档

const nav = navigator as Navigator & { deviceMemory?: number };
const memory = nav.deviceMemory ?? 8;
const cores = navigator.hardwareConcurrency ?? 4;
return memory >= 8 || cores >= 8 ? "high" : "medium";
}

低档位直接不加载 three.js,退回品牌色渐变;three 本体走 next/dynamic + ssr: false 独立懒加载,首屏 JS 里一颗 three 的字节都没有——首页 First Load JS 保持在 108KB 左右。


🔗 第六步:把基地的两个内网系统装进官网

基地有两套内部系统,一直只在群里发个链接,这次一起整合进来。

FTP 资料库(11,455 份 / 132.7GB)

原来是一个独立的单文件 HTML,617KB 的页面里内嵌了整棵目录树 JSON,纯 vanilla JS 渲染。

我在新站里做了个原生页面,功能和它对齐,视觉重新做:

  • 八个分区折叠展开,每个目录懒加载文件清单(11k 个文件的树,初始 DOM 很轻)
  • 全局搜索,命中高亮
  • 任意文件/目录一键复制 ftp:// 完整路径
  • 顶部四格统计:文件数 / 容量 / 分区数 / 文件夹数

数据侧把原来的扫描脚本改造了一下,加了脱敏黑名单(密码、账号类文件自动不入编目)和数量变化的 diff 摘要——以后资料库更新,跑一条命令、看 PR 里的变化,就能提测。

OJ 练习系统

OJ 部署在校园网内网,全站强制登录,外部根本连不上。所以这里不能硬嵌,只能做”中转页”:

  • 打开页面后自动探测能否访问(fetch no-cors + img 双手段兜底)
  • 探测成功 → 亮出「进入 OJ」按钮
  • 探测失败 → 给连接指引(校园 Wi-Fi / 学校 VPN),并给一个可复制的地址

有个小坑:HTTPS 页面去探测 HTTP 内网资源会被混合内容策略拦,所以探测结果只能当参考,手动入口永远保留。


💬 第七步:评论系统,最硬的一仗

旧站的留言板是”借” GitHub Issues 做的——前端直接请求 GitHub API 拉某个 issue 的评论。这个方案有两个硬伤:未认证接口限流 60 次/小时/IP,而且国内访问 GitHub API 很不稳定。

换成了 Waline(自托管,部署在自己的服务器上,数据在自己手里)。选它的另一个关键原因是:它能保住那 22 条历史留言。

这一段是整个项目里最折腾的,简单说几个坑:

坑一:MySQL 8.4 认证插件不兼容

服务器上本来就有 MySQL(8.4),想着直接复用。结果注册管理员的时候报:

1
2
ER_NOT_SUPPORTED_AUTH_MODE: Client does not support
authentication protocol requested by server

MySQL 8.4 默认禁用了老的 mysql_native_password 认证方式,而 Waline 内置的客户端只支持老的。

理论上改一下服务端配置就行,但那台 MySQL 还在给另外两个项目供库——为了一个留言板去重启生产数据库,不值得。 于是直接换成 SQLite:评论这个量级(22 条历史 + 日常零星增量)SQLite 绰绰有余,数据就是一个文件,备份就是复制。

坑二:服务器内存不足,进程被系统杀

那台 ECS 只有 1.8G 内存,还没开 swap。MySQL + Waline + 面板一起上,内核直接把 mysqld 杀了:

1
Out of memory: Killed process 769745 (mysqld)

先加了 2G swap 保命,然后坚持用 SQLite,这关才算过。

坑三:直接写运行中的数据库,把服务写崩了

导入历史留言的时候,我图省事,在容器运行中的情况下用 Python 直接 UPDATE 了 SQLite 文件。结果 Waline 直接原生级崩溃——Node 段错误,日志里只有一串内存地址,连错误信息都不给。

1
2
9: 0xf29af0  [/usr/local/bin/node]
10: 0x19c77d1 [/usr/local/bin/node]

SQLite 单文件数据库被两个进程同时写,WAL 状态就乱了。教训:写库之前必须 docker stop,写完再 docker start。 现在的导入脚本第一行注释就写着这条。

坑四:启动后 5 秒就测,误判成”又崩了”

重建数据库之后,每次 docker start 完等 5 秒就 curl,全部返回连接重置。一度以为又出问题了,其实是带数据库文件启动时 Waline 需要 10 秒左右初始化,5 秒的时候端口还没就绪。

改成轮询:

1
2
3
4
5
for i in $(seq 1 15); do
R=$(curl -s --max-time 3 'http://127.0.0.1:8360/api/comment?path=/')
if [ -n "$R" ]; then echo "$R"; break; fi
sleep 2
done

坑五(真凶):mail = NULL 让列表接口 500

22 条数据导入成功、API 也返回 200,但评论列表一读就报错:

1
TypeError: Cannot read properties of undefined (reading 'replace')

查了很久,最后用了个笨办法定位:让 Waline 自己通过 API 发一条评论,再读它——一切正常。说明问题不在服务,在我们导入的数据。

把 Waline 自己写的那条记录和我们导入的记录逐字段对比,只有两处不同:mail 和 link。补上 mail 的占位值,立刻好了。

原来这版 Waline 读评论时对 mail 调字符串方法,没做判空。让系统自己生成一份“标准答案”,再对照差异,比读源码快十倍。

结果

22 条留言全部迁移上线,昵称、时间、内容、楼中楼关系都保住了。头像这块有点特殊——Waline 按邮箱算头像,而我们的历史留言对应的是 GitHub 账号,所以额外做了个前台补丁:读评论者的 GitHub 主页链接,把头像换成对应的 GitHub 头像。


🏛️ 第八步:旧站归档,不是告别

旧站的文档和博客虽然停更了,但里面有 2019–2021 年写的东西,直接删掉可惜。

做法是:把旧站完整构建一次,产物(133 个文件,4.5MB)挂到新站的 /legacy/ 路径下,顶部加一条归档横幅:

📚 本站为历史归档(2020–2026),内容已冻结不再更新 · ← 返回新站首页

旧站导航栏的「文档」「博客」、页脚的「Git 协作练习」「老版本文档」也全部迁到了新站页脚。旧链接配了 301 映射(/HistoricalHonor/ → /honors/,/docs/ → /legacy/docs/)。

需要说明的是:旧站本身一步都没动。 它的域名、它的内容、它跑的 GitHub Pages,全都原样保留——新站目前只跑在测试子域上。


🚀 第九步:部署到测试子域

服务器是自己的阿里云 ECS,用 1Panel 管理,上面已经有 openresty。流程比想象中简单(纯静态,没有数据库和认证这些麻烦事):

  1. 1Panel 建一个静态网站,指向服务器上的一个目录
  2. 本地 pnpm build 出 out/,Xftp 把产物传上去
  3. 1Panel 里给域名申请 Let’s Encrypt 证书,开强制 HTTPS
  4. 配一条反向代理,让评论服务走同域路径:
1
2
3
4
5
6
7
8
location /comment-api/ {
proxy_pass http://127.0.0.1:8360/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
}

第 4 步是必须的:官网跑在 HTTPS 下,如果评论还去连 http://IP:8360,会被浏览器按混合内容策略直接拦掉,留言板就是一片白。


📌 现在的状态

如实记录一下:

  • ✅ 新站已经跑在测试子域上,功能全通:3D 首页、成员墙、荣誉页、FTP 资料库、OJ 中转、加入我们、旧站归档、评论系统(22 条历史留言在线)
  • ⏳ 还没切主域名。原因有两个:一是需要学长先看过、认可这次重构方向;二是中文域名的备案接入商还需要确认
  • 🛡️ 旧站、旧域名、旧内容全部原样保留,随时可以退回

所以严格来说,这次算是”重构完成、等待验收”,还不能叫上线。等学长点头了,再把主域名解析切过来。


🌱 写在最后

两天做完原本估两周的活,靠的主要是两件事:白嫖的 token 额度,和”每个决策都自己拍板”的工作方式。

但回头看,我觉得这次留下的最有价值的东西,其实不是这个网站——

而是一套能传下去的东西:

  • TUNING.md:3D 场景每个参数在哪、调什么效果,下一届想改配色不用翻代码
  • WALINE部署踩坑记录.md:这次踩的 15 个坑,每个都写了怎么定位
  • MAINTENANCE.md:加成员、加荣誉、更新 FTP 编目、备份评论数据,照着做就行
  • content/ 里的 JSON:以后改内容不用碰代码

技术总会过时,但让别人能接手这件事,什么时代都不过时。

至于这次重构到底能不能被接受——等学长看完再说吧 😌