Nova5 · Battery Materials Personal Site

这是一个以电池材料工程师为主角的个人网站，不是公司官网。网站把个人经历、研究问题、工程项目、证据链和生活兴趣放在同一套视觉语言中：清透的 Fresh Azure 蓝色系统、材料层级示意图、循环曲线和可继续扩展的研究 notes。

当前仓库：samye99/Nova5

重要：代码中的 Your Name、项目状态、实验结果和公开邮箱都是待替换占位符。没有经过本人确认的数据不会被伪装成真实成果；首页的电池结构图和循环曲线明确是概念图。

1. 当前版本做了什么

将原来的企业模板路线替换为个人研究日志路线。
首页结构固定为：研究问题 → 工程项目 → 证据结果 → 工作方法 → notes → 网球/长笛/饮食等生活侧面。
颜色统一为 Fresh Azure：浅蓝白背景、低饱和蓝灰文字、Azure 主强调色和深蓝黑信息层。
用手写 SVG/CSS 绘制电池层级示意图和概念循环曲线，避免使用没有来源的 AI 科学图片或虚构数据。
使用 Astro SSR + @astrojs/cloudflare，部署目标是 Cloudflare Workers。
移除了 Vercel adapter、Vercel 配置、旧企业页面、旧反馈数据库和不再使用的企业内容集合。
保留可选的 Keystatic 本地编辑方式；Cloudflare 生产构建默认通过 SKIP_KEYSTATIC=true 跳过本地管理后台。

2. 页面地图

路径	用途
`/`	个人定位、研究问题、项目精选、证据概览和生活侧面
`/research`	三个核心研究问题与“问题 → 假设 → 构建 → 测量 → 决策”方法
`/projects`	电池材料项目索引；后续在这里替换真实项目、图片、指标和结果
`/evidence`	循环、阻抗、形貌和材料层级之间的证据框架
`/notes`	Markdown/Markdoc 研究笔记列表
`/notes/[slug]`	单篇研究笔记页面
`/about`	化学本科 → 材料学研究生的教育路径、工作方式和生活侧面
`/contact`	联系说明和可选 webhook 联系表单
`/api/contact`	联系表单 API；没有配置 webhook 时为安全 demo 模式
`/api/newsletter`	预留的 newsletter webhook API；目前页脚未启用

3. 内容从哪里改

3.1 个人信息、导航和首页卡片

编辑 src/data/site.ts。这里集中放置：

profile：姓名、职业、简介、GitHub、仓库链接、公开邮箱。
navigationLinks：顶栏和页脚导航。
researchQuestions：三个研究问题。
projects：项目卡片、关注方向和状态标签。
notes：首页 notes 预览标题。
education：化学本科和材料学研究生经历。
outsideLab：网球、长笛、饮食等生活侧面。

第一步建议替换：

profile.name：真实姓名或你希望公开的名字。
profile.email：确认要公开时再填写；留空时页面不会显示邮箱。
profile.role 和 profile.intro：改成真实职位和工作方向。
projects 中的占位状态、真实项目名称、结果和公开范围。
githubUrl、repositoryUrl：确认公开链接没有拼写错误。

3.2 长篇研究笔记

编辑 src/content/notes/。每篇 .mdoc 使用以下 frontmatter：

---
title: 文章标题
description: 一句话说明文章内容
date: 2026-08-04
---

正文可以使用 Markdown/Markdoc。

首页预览的标题和描述仍在 src/data/site.ts，长文正文在 src/content/notes/*.mdoc。如果新增文章，需要让两处 slug 保持一致，或者后续把首页预览改成直接读取内容集合。

3.3 科学视觉元素

src/components/common/LabCellDiagram.astro：电池层级、集流体、电极、隔膜和离子路径的概念图。
src/components/common/EvidenceChart.astro：容量保持率/阻抗增长的概念曲线。
src/assets/styles/global.css：颜色 token、排版、网格背景和通用 panel 样式。

替换概念图时，建议使用本人有权公开的显微照片、材料截面图、真实循环曲线或阻抗图，并在图旁写清楚：样品、测试条件、单位、数据来源和是否经过归一化。

4. Fresh Azure 颜色系统

颜色已经贯穿到导航、按钮、卡片、图表、SVG 和 PWA manifest。主 token 位于 src/assets/styles/global.css：

角色	色值	使用位置
页面背景	`#F5F9FD`	整体页面、浅蓝白底
浅层背景	`#E8F3FB` / `#D5E9F7`	区块、概念图底色
主强调色	`#1F65C1`	CTA、链接、研究编号
活力蓝	`#4DA3E8`	图表线、电池电极渐变
深文字	`#0F1B2A`	深色区块、主要标题
正文文字	`#486078` / `#30465E`	正文和辅助信息
细边框	`#D5E3EF`	卡片、虚线分割线

模板旧代码中保留的 teal-* Tailwind 工具名现在映射到蓝色值，这是为了减少组件改动；视觉上不再使用绿色体系。

5. 本地开发

要求：Node.js >=22，仓库使用 pnpm@10.33.3。

corepack enable
corepack pnpm install
copy .env.template .env        # Windows PowerShell 可用 Copy-Item
corepack pnpm dev

浏览器打开 http://localhost:4321。

常用检查命令：

corepack pnpm run check
corepack pnpm run format:check
corepack pnpm test
corepack pnpm run build:cloudflare

如果要在本地使用 Keystatic：

.env 中不要把 SKIP_KEYSTATIC 设为 true，或者删掉这一行。
使用 KEYSTATIC_STORAGE_MODE=local。
执行 corepack pnpm dev，打开 /keystatic。
修改完成后检查 Git diff，再提交 Markdown/数据文件。

Keystatic 的 GitHub storage 只是编辑辅助方式，不是 Cloudflare 生产后台。Cloudflare 构建会跳过本地文件系统依赖，生产站点不应依赖 /keystatic。

6. Cloudflare Workers 部署

6.1 为什么使用 Workers

该项目使用 Astro SSR 和动态 API，当前 Cloudflare 官方 Astro Workers 指南要求使用 @astrojs/cloudflare。项目已经包含：

astro.config.mjs：output: 'server' + cloudflare()。
wrangler.jsonc：Worker 入口、./dist/client assets、nodejs_compat 和 observability。
public/.assetsignore：避免把 Astro 的 Worker 入口当作普通静态文件上传。
@astrojs/cloudflare@14.1.7 和 wrangler@4.118.0。

官方参考：

6.2 本地部署前检查

corepack pnpm run cf:types
corepack pnpm run build:cloudflare
corepack pnpm run cf:check

cf:check 等价于 wrangler deploy --dry-run，只检查并打包，不上传生产 Worker。构建日志中出现 dist/server/wrangler.json 的 redirected configuration 是 Astro Cloudflare adapter 生成的正常配置，不是错误。

真正部署：

wrangler login
corepack pnpm run cf:deploy

首次部署前，确认终端登录的是正确的 Cloudflare 账号；不要把 API token、.dev.vars 或 .env 提交到 GitHub。

6.3 Cloudflare Workers Builds / GitHub 自动部署

如果希望“修改 GitHub 后自动上传到 Cloudflare”，需要在 Cloudflare 控制台单独连接仓库。仅仅把代码推送到 GitHub 不会自动部署。

建议设置：

Cloudflare 设置	值
GitHub repository	`samye99/Nova5`
Production branch	`main`
Root directory	`/`
Build command	`corepack pnpm run build:cloudflare`
Deploy command	`corepack pnpm exec wrangler deploy`
Node.js	`22` 或更高
Package manager	pnpm，使用仓库 `packageManager` 字段

环境变量：

PUBLIC_SITE_URL：实际的 workers.dev 地址或自定义域名，例如 https://your-name.workers.dev。这是 SEO canonical URL，不是密钥。
SKIP_KEYSTATIC=true：生产构建必须设置，避免把本地 Keystatic 管理路由和文件系统假设带进 Worker。

推荐流程：

本地修改 → pnpm run check → pnpm run build:cloudflare
       → pnpm run cf:check → push GitHub
       → Cloudflare Workers Builds 预览 → 合并 main → 生产部署

本仓库的开发分支不会自动替换生产 main。如果 Cloudflare 的 production branch 是 main，需要合并后才会触发生产部署；如果要先看预览，应让 Cloudflare 开启 branch preview 或使用单独的 preview Worker。

6.4 API 和表单说明

/api/contact 和 /api/newsletter 使用标准 fetch，可以在 Workers 运行。
没有设置 webhook 时，接口只做校验并返回 demo 成功，不会发送邮件。
如果未来要连接第三方服务，优先使用 Cloudflare Worker secret 或第三方平台的安全环境变量，不要把 token 写到 PUBLIC_* 或提交到 .env。
目前网站没有数据库依赖；不需要绑定 D1、Turso 或本地 SQLite 才能部署。
Cloudflare adapter 在构建时会生成所需的 Worker 运行配置；当前站点本身没有主动使用 Images/KV 数据。

7. GitHub 修改后的检查顺序

每次修改后建议按这个顺序：

corepack pnpm run check
corepack pnpm run format:check
corepack pnpm run build:cloudflare
corepack pnpm run cf:check
git diff --check
git status

重点人工复检：

页面标题、姓名、邮箱、公司和项目结果是否都是本人确认过的内容。
图表旁是否有测试条件；没有真实数据时是否仍标注为 illustrative/conceptual。
手机端导航、按钮焦点、跳过主内容链接和 prefers-reduced-motion 是否正常。
Cloudflare 的生产 branch、构建命令和 PUBLIC_SITE_URL 是否指向同一套部署。

8. 常见问题

构建时提示缺少 packages / lockfile 不一致

在仓库根目录执行：

corepack pnpm install --frozen-lockfile
corepack pnpm run build:cloudflare

不要在 Cloudflare 控制台把项目强制改成 npm 或 Vercel 的构建方式。

Cloudflare 构建找不到 Keystatic 或本地文件

确认 Cloudflare 环境变量包含：

SKIP_KEYSTATIC=true

Keystatic 用于本地编辑；生产站点只发布生成后的个人主页和 notes。

页面地址可以打开，但 canonical URL 错了

把 Cloudflare 中的 PUBLIC_SITE_URL 改成真实 Workers/custom domain 地址，然后重新构建部署。不要把示例值 https://your-worker.workers.dev 留在生产环境。

想添加真实显微图或电池曲线

先确认图片和数据有公开授权，再放入 public/ 或 Astro asset 目录；同时在页面中补充样品、条件、单位和来源。不要直接把公司内部截图、未经批准的数据或 AI 生成的“实验结果”当作成果图。

9. 目录速查

Nova5/
├─ astro.config.mjs             # Astro + Cloudflare SSR 配置
├─ wrangler.jsonc               # Cloudflare Workers 配置
├─ public/.assetsignore         # Worker assets 排除项
├─ src/data/site.ts             # 个人资料、导航、项目和首页文案
├─ src/content/notes/           # 可编辑的长篇研究笔记
├─ src/components/common/       # 电池结构图、证据图
├─ src/components/sections/     # 导航、页脚、研究/项目/方法区块
├─ src/layout/BaseLayout.astro  # 全局 SEO、主题和页面外壳
├─ src/pages/                   # 网站路由
├─ src/pages/api/               # 联系/订阅 API
├─ src/assets/styles/global.css # Fresh Azure token 与全局样式
├─ keystatic.config.ts          # 可选的本地 notes 编辑配置
├─ .env.template                # 非敏感环境变量模板
└─ README.md                    # 本备份与部署手册

10. 维护原则

先写清问题，再添加视觉效果。
所有真实成果都要能回到数据、条件和公开权限。
颜色通过 global.css token 修改，不要在组件里重新发明一套蓝色。
Cloudflare 的部署只认仓库中的 wrangler.jsonc、锁文件和构建命令。
每次 GitHub 修改后，至少完成 check、Cloudflare build 和 cf:check 再合并生产分支。

Name		Name	Last commit message	Last commit date
Latest commit History 846 Commits
.github		.github
docs/superpowers/plans		docs/superpowers/plans
public		public
src		src
.env.template		.env.template
.gitignore		.gitignore
.prettierrc		.prettierrc
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
README.md		README.md
astro.config.mjs		astro.config.mjs
keystatic.config.ts		keystatic.config.ts
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
wrangler.jsonc		wrangler.jsonc

Navigation Menu

Repository files navigation

Nova5 · Battery Materials Personal Site

1. 当前版本做了什么

2. 页面地图

3. 内容从哪里改

3.1 个人信息、导航和首页卡片

3.2 长篇研究笔记

3.3 科学视觉元素

4. Fresh Azure 颜色系统

5. 本地开发

6. Cloudflare Workers 部署

6.1 为什么使用 Workers

6.2 本地部署前检查

6.3 Cloudflare Workers Builds / GitHub 自动部署

6.4 API 和表单说明

7. GitHub 修改后的检查顺序

8. 常见问题

构建时提示缺少 packages / lockfile 不一致

Cloudflare 构建找不到 Keystatic 或本地文件

页面地址可以打开，但 canonical URL 错了

想添加真实显微图或电池曲线

9. 目录速查

10. 维护原则

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Nova5 · Battery Materials Personal Site

1. 当前版本做了什么

2. 页面地图

3. 内容从哪里改

3.1 个人信息、导航和首页卡片

3.2 长篇研究笔记

3.3 科学视觉元素

4. Fresh Azure 颜色系统

5. 本地开发

6. Cloudflare Workers 部署

6.1 为什么使用 Workers

6.2 本地部署前检查

6.3 Cloudflare Workers Builds / GitHub 自动部署

6.4 API 和表单说明

7. GitHub 修改后的检查顺序

8. 常见问题

构建时提示缺少 packages / lockfile 不一致

Cloudflare 构建找不到 Keystatic 或本地文件

页面地址可以打开，但 canonical URL 错了

想添加真实显微图或电池曲线

9. 目录速查

10. 维护原则

About

Resources

Code of conduct

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages