astro-jiao77.cn/README.md

astro-jiao77.cn

一个基于 Astro 5、TypeScript 与 Tailwind CSS 打造的现代静态网站，融合玻璃质感设计、莫兰蒂配色与定制动画系统，适合构建专题站点、数据报告与导航中心。

项目简介

• 使用 Astro 的岛屿架构实现快速加载与细粒度交互。
• Tailwind CSS 提供统一的设计令牌与主题扩展，支持深浅配色切换。
• 组件库涵盖导航、报告、通用 UI 与动画包装器，降低页面搭建成本。
• 内置部署脚本与检查流程，支持快速上线与质量验证。

环境要求

工具	建议版本	说明
Node.js	≥ 18.17.0	可用 nvm 管理不同版本
npm / pnpm	npm ≥ 9 / pnpm ≥ 8	根据团队习惯选择包管理器
Git	最新版本	代码管理与部署同步

快速开始

1. 安装依赖

   npm install
   

2. 启动开发服务器（默认端口 4321）

   npm run dev
   

3. 构建与预览产物

   npm run build
   npm run preview
   

4. 类型与模板检查

   npm run astro check
   

目录结构

.
├─ src/
│  ├─ components/
│  │  ├─ common/                # 通用组件（按钮、动画包装、图像查看器等）
│  │  ├─ navigation/            # 导航页面组件 (NavigationCard、NavigationGrid)
│  │  └─ report/                # 报告组件 (ReportSection、MetricCard、MetricsGrid)
│  ├─ layouts/                  # 布局组件 (BaseLayout 等)
│  ├─ pages/                    # Astro 页面 (首页、报告模板、专题页)
│  └─ scripts/                  # 浏览器交互脚本 (滚动、头部动画等)
├─ docs/                        # 说明文档与部署指南
├─ public/                      # 静态资源 (图片、图标、字体等)
├─ tailwind.config.mjs          # 主题与配色扩展
├─ deploy.sh / deploy-full.sh   # 部署脚本
└─ astro.config.mjs             # Astro 全局配置

常用命令

命令	功能
npm run dev	本地开发，支持热更新
npm run build	产出静态文件到 dist/
npm run preview	使用 Astro 内置服务器预览构建结果
npm run astro check	运行 TypeScript + Astro 模板检查
npm run lighthouse	（如配置）执行性能与可访问性检测

核心模块与文件

• 报告模板：src/pages/report/template/index.astro，配合 docs/REPORT_TEMPLATE_SUMMARY.md 快速复用结构。
• 导航模板：src/pages/navigation-template.astro，搭配 docs/NAVIGATION_TEMPLATE_GUIDE.md 定制导航入口。
• 交互脚本：src/scripts/scroll-progress.ts、src/scripts/header.ts 管理滚动进度条与动态头部。
• 通用组件：src/components/common/AnimatedElement.astro、GlowButton.astro、ImageViewer.astro 提供动画与图片交互。
• 配色定义：tailwind.config.mjs 中的 morandi 调色盘，实现统一的莫兰蒂主题。

页面与组件使用

导航页面

• 组合 NavigationGrid 与 NavigationCard 构建入口矩阵。
• 支持自定义列数、动画延迟与卡片主题，适用于首页、功能导航等场景。

报告页面

• 使用 ReportSection 划分章节，搭配 MetricCard、MetricsGrid 展示核心指标。
• 支持深色渐变背景与滚动触发动画，适合数据报告、分析仪表盘。

通用组件

• Container：多种视觉变体（glass、solid、outline）与尺寸可选。
• AnimatedElement：封装 8 种滚动动画，支持延迟与持续时间配置。
• Header：响应滚动的智能页眉，移动端自适应。

设计与交互

• 玻璃质感：半透明背景 + 模糊滤镜，营造层次感。
• 莫兰蒂配色：柔和雅致，适用于深浅背景。定义示例：

  morandi: {
    cream: '#F4F1E8',
    beige: '#E8DCC0',
    sage: '#C8D5B9',
    dusty: '#D4B5A0',
    mauve: '#B8A5A5',
    clay: '#A68B7B',
    mist: '#C7B8A1',
    stone: '#9B8B7A',
    deep: '#7A6B5D'
  }
  

• 动画系统：加载、滚动、悬浮多种动效，增强反馈与沉浸感。
• 响应式布局：针对桌面、平板、移动端优化栅格与交互。

开发流程

1. 基于模板创建页面：复制 pages/report/template 或现有导航页。
2. 在 src/components/ 中组合组件，必要时拓展新变体。
3. Tailwind 实现局部样式，注意复用 @apply 与设计令牌。
4. 若需脚本交互，将逻辑放入 src/scripts/ 并在页面中按需引入。
5. 执行 npm run astro check 与 npm run build 确保质量。

部署流程

1. 本地构建：npm run build
2. 根据上线需求选择：
   • ./deploy.sh：快速增量部署
   • ./deploy-full.sh：完整部署，包含权限校验、压缩检测
3. 部署验证请参考 docs/DEPLOYMENT.md 与 docs/DEPLOY_FULL_VERIFICATION.md
4. 上线后建议检查服务器日志与浏览器控制台，确保资源加载正常。

调试技巧

• 利用浏览器 DevTools 观察 CSS 变量与动画帧率。
• Astro CLI 支持 --open、--host，例如 npm run dev -- --host 供局域网调试。
• 对滚动行为可在控制台监听 scroll-progress 脚本的状态输出。
• 若遇到类型问题，运行 npm run astro check -- --watch 进行持续监控。

技术栈

• Astro：静态站点生成 + 部分组件岛屿渲染。
• Tailwind CSS：实用类样式与主题扩展。
• TypeScript：类型安全与更佳的开发体验。
• Font Awesome / 自定义图标：图标资源。
• Vite：开发服务器与构建工具。

贡献指南

欢迎提交 Issue 或 Pull Request 改进项目。建议遵循以下流程：

1. Fork 仓库并创建新分支。
2. 完成改动后运行 npm run build 与相关检查。
3. 提交 PR 并在描述中说明变更内容及影响范围。