Leon 技术博客技术栈教程

项目当前的真实运行时数据源是 Supabase。历史 Markdown 已经归档到 content/archive/posts，只用于人工核对和历史留存，不再作为前台渲染或后台编辑的回退来源。

• Next.js 16 App Router 负责页面、API routes、metadata、ISR 和静态参数生成。
• React 19 与 Server Components 是默认渲染模型，交互组件才显式使用 client boundary。
• TypeScript 开启 strict、noImplicitAny、noUncheckedIndexedAccess 等较严格约束。
• Supabase posts 表保存文章正文、元信息、发布状态、双语 shared_id 和阅读量。
• Cloudflare R2 保存图片资产，后台上传接口返回公开 CDN URL。

pnpm install
pnpm dev
pnpm type-check
pnpm lint
pnpm build

根路径 app/page.tsx 会跳转到 /en；前台内容集中在 app/[locale]，目前支持 en 与 zh。/docs 是独立公开文档入口，不参与 locale 前缀，便于形成 nodz.site/docs 这样的固定路径。

• app/[locale]/layout.tsx 使用 next-intl 的 NextIntlClientProvider 提供多语言消息。
• generateStaticParams 只生成配置中的 locale，dynamicParams=false 避免未知 locale 被当作合法页面。
• 文章详情页使用 revalidate=3600，列表、标签、分类、Lab 等页面也通过 ISR 降低请求成本。
• metadataBase、canonical、Open Graph、RSS、sitemap 和 robots 都依赖 NEXT_PUBLIC_SITE_URL 或 SITE_URL。

app/
  [locale]/          # 前台多语言页面
  admin/             # 管理后台
  api/               # Route Handlers
  docs/page.tsx      # 技术栈文档中心
lib/
  posts.ts           # 前台文章读取与缓存
  supabase/          # 数据库类型与读写
  r2/                # R2 素材管理
proxy.ts             # 限流、安全过滤、后台认证

全局样式位于 app/globals.css，使用 Tailwind v4 的 @theme inline 把 CSS variables 映射为设计 token。主题色通过 data-color-theme 切换，暗色模式由 next-themes 管理。

• 默认优先使用 Server Components，搜索、主题切换、后台表单、编辑器等交互区域才使用 client components。
• 重型视觉元素和搜索弹窗通过 dynamic import 延迟加载，减少首屏负担。
• 前台 Header/Footer 依赖 next-intl，因此独立 /docs 页面使用自己的轻量文档导航。
• 固定格式 UI 要有明确尺寸和响应式约束，代码块与表格在移动端横向滚动。

Markdown 渲染相关组件集中在 components/articles。MarkdownContent 负责正文输出，LazyTableOfContents 和 LazyGiscusComments 负责按需加载目录与评论，ViewCounter 在客户端触发阅读量接口。

lib/supabase/server.ts 使用 service role key 创建服务端客户端，只应在 Server Components、API routes 和脚本中使用。lib/supabase/client.ts 使用 anon key，适合浏览器端只读或受 RLS 保护的场景。

• posts 表通过 locale + slug 保证单语言唯一，通过 shared_id 关联中英文翻译。
• 发布逻辑要求双语 pair 准备好后一起发布，避免前台语言切换指向缺失内容。
• getAllPostsFromSupabase 读取 Supabase，lib/posts.ts 再用 unstable_cache 做 60 秒 Data Cache。
• getPostBySlug 会把数据库字段映射为前台 Post，并补充阅读时长、摘要、封面、转载来源等展示字段。
• 阅读量接口 app/api/posts/[slug]/view/route.ts 负责查询与自增 view_count。

Supabase posts
  -> lib/supabase/posts.ts
  -> lib/posts.ts cached mapper
  -> app/[locale]/posts/page.tsx
  -> app/[locale]/posts/[slug]/page.tsx
  -> components/articles/*

管理员登录使用 app/api/auth/login/route.ts 校验账号密码，成功后写入 HttpOnly admin_session cookie。proxy.ts 会拦截 /admin 路径并校验 JWT，有问题时重定向到 /admin/login。

next.config.ts 开启 output=standalone、压缩、远程图片白名单、静态资源缓存和安全 headers。Vercel 负责构建部署，Cloudflare 可承担 DNS、R2 自定义域名、流量保护和 Worker 代理等能力。

NEXT_PUBLIC_SITE_URL=https://your-domain.com
SITE_URL=https://your-domain.com

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-supabase-service-role-key

JWT_SECRET=your-long-random-jwt-secret
ADMIN_PASSWORD=your-admin-password
IKUN_PASSWORD=your-second-admin-password

R2_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
R2_BUCKET=your-r2-bucket
R2_ACCESS_KEY_ID=your-r2-access-key-id
R2_SECRET_ACCESS_KEY=your-r2-secret-access-key
R2_PUBLIC_URL=https://assets.your-domain.com

OPENAI_CUSTOM_BASE_URL=https://your-openai-compatible-endpoint/v1
OPENAI_CUSTOM_API_KEY=your-openai-compatible-key
OPENAI_MODEL_PRIMARY=your-primary-model
OPENAI_MODEL_FALLBACK=your-fallback-model

1. 1本地拉起 pnpm dev，验证 /en、/zh、/docs 和 /admin/login。
2. 2内容新增优先进入后台创建草稿，不再把 content/posts 当作生产入口。
3. 3中英文草稿都准备好后，通过后台双语发布按钮一起发布。
4. 4图片通过后台上传或 R2 脚本上传，正文中使用 R2_PUBLIC_URL 下的公开地址。
5. 5上线前运行 pnpm type-check、pnpm lint、pnpm build。

pnpm dev                 # Turbopack 开发服务
pnpm dev:fast            # 增大 Node 内存的开发服务
pnpm type-check          # TypeScript 类型检查
pnpm lint                # ESLint
pnpm build               # 生产构建
pnpm analyze             # Bundle analyzer
pnpm translate:blog      # 翻译博客草稿
pnpm sync:supabase       # 同步历史内容到 Supabase
pnpm sync:telegram       # 同步文章到 Telegram/Telegraph

• SUPABASE_SERVICE_ROLE_KEY 只能在服务端使用，不能进入 client component 或 NEXT_PUBLIC 变量。
• JWT_SECRET、ADMIN_PASSWORD、R2_SECRET_ACCESS_KEY、AI API key 必须只放在环境变量里。
• proxy.ts 对 /api、/api/admin、/api/auth 和普通页面设置不同限流阈值。
• next.config.ts 设置 CSP、HSTS、X-Frame-Options、Referrer-Policy、Permissions-Policy 等安全 headers。
• R2 删除接口会扫描文章引用，删除素材前要确认没有被其他文章复用。