qzl/eryao

Files

T

zl-q c12320cb79 feat(web): rebuild web with Astro 6 + React 19 + Tailwind 4

Replace static HTML website with Astro SSG framework:
- Astro 6 + React 19 (client islands) + Tailwind CSS 4 + shadcn/ui
- i18n: zh/zh_Hant/en with URL prefix routing
- Pages: Landing, Features, Pricing, About, Privacy, Terms (3 locales)
- Responsive full-width layout with scroll reveal animations
- Cyber gradient theme with particle effects inspired by Kimi
- Features page: alternating layout with hexagram illustrations
- Legal pages: markdown rendering with side info card
- Language switcher preserves current page path
- Assets shared via symlinks to web/design/assets/ (no duplication)

Tech decisions documented in .trellis/spec/web/index.md
Task: .trellis/tasks/05-08-web-astro-react-tailwind-shadcn-ui

2026-05-09 12:11:10 +08:00

4.9 KiB

Raw Blame History

Web 端技术选型 PRD

背景

eryao 项目需要建设 Web 端。移动端已有 Flutter 应用（iOS/Android），后端为 Python FastAPI + Supabase。Pencil 设计稿已完成（web/design/eryao.pen），包含 19 个页面。

设计稿分析

页面分类

营销/公开页面（需要 SEO）：

Landing Page — Hero + Showcase + Testimonials + CTA + Footer
Features Page — 功能特性展示
Pricing Page — 定价方案卡片
About Page — 关于我们 + 法律声明
Privacy Policy Page
Terms of Service Page

Dashboard/应用页面（Auth 后 SPA）：

Login Page — 登录表单卡片
Dashboard — 侧边栏(260px) + 主区域(1180px) 布局
NotificationPage — 通知列表
其余 9 个页面（待展开）

设计特征

宽度 1440px，桌面端为主
色系：紫色主色(#7C3AED)、深蓝底色(#0F172A/#020617)、白色/浅灰背景
渐变背景（linear-gradient）、圆角(16px)、阴影(blur 24px)
全部色值来自 Tailwind CSS 默认色板
i18n 支持：zh / zh_Hant / en（与移动端一致）

技术选型

决策：Astro 5 + React + Tailwind CSS 4 + shadcn/ui

选型理由

1. Astro 5 作为框架

考量	结论
营销页 SEO	Astro 默认零 JS 输出，SSG 开箱即用，SEO 最优
Dashboard SPA	React islands 模式，客户端全功能渲染
安全性	静态生成，无服务端运行时，攻击面极小
无已知 CVE	搜索未发现 Astro 框架本身的 CVE 记录

为什么不用 Next.js：

CVE-2025-55182（CVSS 10.0 "React2Shell"）RCE，已被武器化
CVE-2025-29927 中间件鉴权绕过
CVE-2025-66478 Next.js 对应编号，766 台主机被入侵
Server Components 攻击面大，对于本项目过度设计

为什么不用 Vite + React SPA：

营销页 SEO 差，需要额外 SSR 方案
两个场景（营销+应用）用一套框架更简洁

2. React 作为交互层

shadcn/ui 原生 React，组件覆盖度最高
Astro islands 一等公民支持
生态最大，Dashboard 复杂交互组件丰富

关于 CVE-2025-55182： 该漏洞仅影响 React Server Components（RSC），即 Next.js App Router 服务端渲染场景。我们的架构使用 Astro SSG + React 客户端 islands，不使用 RSC，漏洞不适用。

3. Tailwind CSS 4

设计稿色值全部来自 Tailwind 色板，零适配成本
渐变、flexbox、阴影、圆角全部原生支持
无已知直接漏洞（Snyk 确认）
v4 已修复 v3 的 glob 传递依赖问题

4. shadcn/ui

源码级复制，可完全自定义，无锁定
Card / Button / Input / Form / Sidebar 等组件与设计稿高度吻合
无已知直接漏洞（Snyk 确认）
只使用官方 registry，避免第三方 registry 注入风险

架构概览

web/
├── src/
│   ├── components/        # 共享 UI 组件（shadcn/ui + 自定义）
│   │   ├── ui/            # shadcn/ui 组件
│   │   ├── Navbar.astro   # 营销页导航栏
│   │   ├── Footer.astro   # 营销页页脚
│   │   └── Sidebar.tsx    # Dashboard 侧边栏（React island）
│   ├── layouts/
│   │   ├── Marketing.astro    # 营销页布局（Navbar + Footer）
│   │   └── Dashboard.astro    # Dashboard 布局（Sidebar + Main）
│   ├── pages/
│   │   ├── index.astro        # Landing Page
│   │   ├── features.astro     # Features Page
│   │   ├── pricing.astro      # Pricing Page
│   │   ├── about.astro        # About Page
│   │   ├── privacy.astro      # Privacy Policy
│   │   ├── terms.astro        # Terms of Service
│   │   ├── login.astro        # Login Page（含 React island）
│   │   └── dashboard/
│   │       ├── index.astro    # Dashboard（含 React island）
│   │       └── notifications.astro
│   └── styles/
│       └── global.css         # Tailwind 入口
├── astro.config.mjs
├── tailwind.config.ts
├── tsconfig.json
└── package.json

API 集成

后端：FastAPI（已有）
Auth：Supabase Auth JS SDK（客户端）
数据：通过 FastAPI REST API + Supabase JS SDK

i18n 方案

使用 astro-i18next 或 @astrolicious/i18n 处理 Astro 页面
React islands 使用 react-i18next
翻译文件与移动端共享（zh / zh_Hant / en）

部署

营销页：SSG 静态部署（Vercel / Cloudflare Pages / 自托管）
Dashboard SPA：同一构建产物，客户端渲染
无需 Node.js 服务端运行时

验收标准

所有设计稿页面可在浏览器中像素级还原
营销页 Lighthouse SEO 评分 >= 95
Dashboard 侧边栏导航和主区域交互正常
i18n 三语言切换正常
无安全漏洞（npm audit clean）
设计稿中所有渐变、阴影、圆角、布局精确匹配

4.9 KiB Raw Blame History Unescape Escape