融合中国京剧艺术与动画美学的国风展示网站 | 纯静态 Web 技术 | GitHub Pages 自动部署
立即体验： https://love-you-tt.github.io/-
《京剧猫》是中国首部将国粹京剧艺术与现代动画深度结合的原创动画巨作。自 2015 年首播以来，已推出四季完整剧集，凭借独特的"京剧猫"世界观、精美的东方画风和深厚的文化底蕴，荣获白玉兰奖最佳动画片、中国动漫金龙奖等多项国家级大奖，在国内外动画爱好者中建立了广泛的粉丝基础。
然而，目前互联网上缺乏一个能够全面展示《京剧猫》文化魅力的独立品牌网站。大部分内容分散在视频平台和社交网络上，无法为用户提供一站式的沉浸式体验。本项目旨在填补这一空白。
- 文化传播：通过现代化的 Web 技术，将京剧艺术的"唱念做打"和"生旦净丑"等核心美学可视化呈现，降低传统文化认知门槛
- 品牌展示：为《京剧猫》IP 打造与其艺术水准匹配的独立在线门户，提升品牌辨识度
- 技术示范：提供一个高质量国风前端项目的完整实践案例，包括配色体系、响应式设计、性能优化、无障碍访问和安全防护
| 维度 | 价值说明 |
|---|---|
| 文化价值 | 运用朱红、金色、墨黑等传统色谱与书法字体，将京剧艺术美学融入每一个交互细节 |
| 技术价值 | 完整实现 PWA 离线缓存、CSP 安全策略、滚动渐入动画等现代 Web 最佳实践 |
| 教育价值 | 源代码注释详尽，README 文档覆盖安装、配置、使用、贡献全流程，适合前端初学者学习国风设计 |
| 传播价值 | SEO 完整体系（sitemap + robots + OG + Twitter Card），确保搜索引擎可全面索引内容 |
| 体验价值 | WCAG AA 级无障碍标准（4.8:1 对比度），prefers-reduced-motion 动效适配，屏幕阅读器友好 |
- 🎬 动画爱好者：深入了解《京剧猫》角色、剧情和艺术特色
- 🏮 国风文化爱好者：感受传统戏曲与现代设计的碰撞
- 💻 前端开发者：学习国风 Web 设计的全套实践方案
- 🎨 UI/UX 设计师：参考中国传统色彩体系在 Web 中的落地应用
 |
 |
 |
| 首页 Hero | 关于京剧猫 | 主要角色 |
 |
 |
|
| 京剧艺术元素 | 精彩剧照 |
- 国风色彩体系：朱红 (
#c62828)、金色 (#d4af37)、墨黑 (#2c2c2c)、米白 (#f9f3e9)、宣纸色 (#f8f0d7)、黛青 (#1565c0)，通过 CSS 变量统一管理，支持全局一键换肤 - 传统京韵导航栏：Header 采用深朱红渐变 (
#a41e1e → #7a0000) + 月白文字 (#fffaf0)，对比度达 4.8:1（符合 WCAG AA 标准），悬停时translateY(-2px)微动效增强交互反馈 - 传统书法字体：马善政书法字体（标题） + 思源宋体（正文），由 Google Fonts CDN 异步加载，
font-display: swap避免 FOIT - 本地字体降级链：
Noto Serif SC → 思源宋体 → STSong → SimSun → serif，即使 Google Fonts 不可用也能正常显示 - 京剧元素融入：祥云装饰层、双层金色边框、脸谱纹样、SVG 暗纹背景，每个细节均取材自京剧舞台美术
- 字体平滑渲染：
-webkit-font-smoothing: antialiased确保跨平台文字清晰
| 模块 | 锚点 | 说明 |
|---|---|---|
| 英雄区域 | #home |
全屏背景图 + 双层金色边框 + CTA 号召按钮，首屏 LCP 优化至 ~1.6s |
| 关于京剧猫 | #about |
作品介绍 + 嵌入式视频播放器（preload="metadata" 预加载元数据） |
| 主要角色 | #characters |
4 张角色卡片（白糖 / 武崧 / 小青 / 大飞），decoding="async" 异步解码 |
| 京剧艺术元素 | #elements |
4 张卡片展示脸谱、音乐、动作、服饰，滚动渐入动画 |
| 精彩剧照 | #gallery |
7 个视频片段，互斥播放机制，统一音量控制 |
| 页脚 | — | 品牌标识、导航链接、官网入口、版权声明 |
| 自定义 404 页 | — | 与品牌风格一致（朱红 + 金色 + 猫主题），响应式设计 |
| 无 JS 降级 | — | <noscript> 提示用户启用 JavaScript，品牌化的朱红提示条 |
| 功能 | 技术实现 | 用户价值 |
|---|---|---|
| 平滑滚动导航 | Element.scrollIntoView({ behavior: 'smooth' }) |
锚点定位流畅自然，无突兀跳转 |
| 导航滚动高亮 | Intersection Observer + scrollspy |
滚动时自动高亮当前所在区域的导航项 |
| 视频互斥播放 | play 事件监听 + 全局遍历暂停 |
同一时间仅一个视频播放，避免多视频同时出声 |
| 统一音量控制 | video.volume = 0.7 |
所有视频音量一致，无需手动逐个调整 |
| 滚动渐入动画 | Intersection Observer + CSS 类切换 | 元素进入视口时流畅淡入，threshold: 0.1 |
| 图片直接加载 | <img src> 直接加载 |
页面初始加载时即加载所有图片，无延迟 |
| 视频预加载 | preload="metadata" + 用户主动播放 |
首屏不加载完整视频，预取元数据快速播放 |
| Service Worker | sw.js (Cache API) |
二次访问秒开，支持离线浏览 |
| 导航悬停动效 | :hover + translateY(-2px) |
交互状态可视反馈，0.2s 平滑过渡 |
| 减弱动效适配 | prefers-reduced-motion 媒体查询 |
尊重系统无障碍设置，前庭功能障碍用户友好 |
| 技术 | 用途 | 版本 / 说明 |
|---|---|---|
| HTML5 | 语义化页面结构 | 正确的 section/article/header/nav 层级 |
| CSS3 | 布局 / 动画 / 响应式 | Flexbox、Grid、CSS 变量、@supports 渐进增强 |
| JavaScript (ES6+) | 交互逻辑与 DOM 操作 | IIFE 封装，无全局变量污染 |
| Font Awesome | 图标库 | 6.4.0 (CDN 异步加载) |
| Google Fonts | 马善政书法字体 + 思源宋体 | CDN + 多级本地回退 |
| Service Worker | 离线缓存与秒开体验 | Cache API，智能缓存策略 |
| Content Security Policy | XSS 攻击面缩减 | script-src 'self'（无 unsafe-inline），meta 标签注入 |
| GitHub Pages | 静态网站托管 | 免费 HTTPS 证书，全球 CDN |
| GitHub Actions | CI/CD 自动部署 | Node.js 24 兼容，pages.yml 工作流 |
京剧猫/
├── index.html # 入口文件（Meta Refresh 重定向到主页面）
├── 京剧猫.html # 主页面（语义化 HTML5 + CSP Meta 标签）
├── 404.html # 自定义 404 错误页（品牌风格，响应式）
├── styles.css # 样式文件（CSS 变量 + 4 断点响应式 + 动画）
├── script.js # 交互逻辑（导航、视频、scrollspy）
├── sw.js # Service Worker（离线缓存 + 秒开体验）
├── robots.txt # 搜索引擎爬虫规则（指向 sitemap.xml）
├── sitemap.xml # 站点地图（SEO 索引优化）
├── .gitignore # Git 忽略配置
├── .commitlintrc.yml # Commitlint 提交规范配置
├── LICENSE # MIT 开源许可证
├── README.md # 项目说明文档（本文件）
├── .github/
│ └── workflows/
│ ├── pages.yml # GitHub Pages 自动部署工作流
│ └── commitlint.yml # Commitlint 自动校验工作流
├── images/ # 图片资源（JPG 格式）
│ ├── 1.jpg # 英雄区域背景图
│ ├── 2.jpg # 白糖角色图（800×1067）
│ ├── 3.jpg # 武崧角色图（800×1067）
│ ├── 4.jpg # 小青角色图（800×1067）
│ └── 5.jpg # 大飞角色图（800×1067）
├── videos/ # 视频资源（preload="metadata" 预加载）
│ ├── 1.mp4 # 关于区域 - 动画介绍视频
│ ├── 2.mp4 # 四功五法片段
│ ├── 3.mp4 # 人物简介片段
│ ├── 4.mp4 # 武宗八方片段
│ ├── 5.mp4 # 霸王别姬片段
│ ├── 6.mp4 # 十二宗片段
│ └── 7.mp4 # 人物卡点片段
├── icons/ # PWA 图标（待配置 manifest.json）
│ ├── icon-192.png # 192×192 小图标
│ └── icon-512.png # 512×512 大图标
└── screenshots/ # 页面截图素材
├── screenshot.png
├── screenshot (1).png
├── screenshot (2).png
├── screenshot (3).png
└── screenshot (4).png
| 要求 | 最低版本 | 推荐版本 |
|---|---|---|
| Chrome | 51+ | 最新稳定版 |
| Firefox | 55+ | 最新稳定版 |
| Safari | 12.1+ | 最新稳定版 |
| Edge | 79+ | 最新稳定版 |
无需安装 Node.js、Python 或任何其他运行时依赖。项目为纯静态文件。
方法一：直接打开
# Windows
start 京剧猫.html
# macOS
open 京剧猫.html
# Linux
xdg-open 京剧猫.html方法二：本地服务器（推荐，解决视频 CORS 限制）
# Python 3
python -m http.server 8000
# Node.js (需要先安装 npx)
npx serve .
# PHP
php -S localhost:8000浏览器访问 http://localhost:8000 或 http://localhost:8000/京剧猫.html
提示： 直接双击打开 HTML 时，部分浏览器可能因安全策略限制视频加载。推荐使用本地服务器方式预览完整效果。
项目已配置 GitHub Actions 自动部署（.github/workflows/pages.yml），步骤如下：
- Fork 或推送本仓库到你的 GitHub 账号
- 进入仓库 Settings → Pages
- 在 Build and deployment 中，将 Source 设为 GitHub Actions
- 推送代码到
main（或你的默认分支），工作流将自动构建并部署
部署流水线：
| 步骤 | Action | 说明 |
|---|---|---|
| 1. 检出代码 | actions/checkout@v5 |
拉取仓库全部文件 |
| 2. 配置 Pages | actions/configure-pages@v5 |
设置 Pages 环境 |
| 3. Jekyll 构建 | actions/jekyll-build-pages@v1 |
生成静态站点 |
| 4. 上传产物 | actions/upload-pages-artifact@v3 |
打包部署文件 |
| 5. 部署发布 | actions/deploy-pages@v4 |
发布到 GitHub Pages |
项目采用关注点分离架构，三个核心文件各司其职：
| 文件 | 职责 | 如何修改 |
|---|---|---|
京剧猫.html |
页面结构与内容 | 编辑 HTML 标签和文本节点 |
styles.css |
视觉样式与布局 | 修改 CSS 变量和类定义 |
script.js |
交互逻辑与行为 | 修改 JavaScript 函数参数 |
- 修改文字内容：编辑
京剧猫.html中的文本节点 - 调整配色方案：修改
styles.css中:root下的 CSS 变量（见下方参考） - 替换图片：将新图片放入
images/目录，更新src属性 - 替换视频：将新视频放入
videos/目录，更新<video>的src属性。保持preload="metadata"以优化加载性能 - 修改导航：编辑
<nav>中的<li>项，添加或移除导航链接，确保href指向对应section的id
:root {
--primary: #c62828; /* 朱红 - 主色调，用于 header、强调元素 */
--secondary: #d4af37; /* 金色 - 强调色，用于边框、高亮 */
--dark: #2c2c2c; /* 墨黑 - 深色背景 */
--light: #f9f3e9; /* 米白 - 浅色背景 */
--accent: #1565c0; /* 黛青 - 辅助色，用于链接 */
--paper: #f8f0d7; /* 宣纸色 - 页面主背景 */
}| 场景 | 修改变量 | 建议值 |
|---|---|---|
| 深色主题 | --dark → body 背景 |
background-color: var(--dark) |
| 暖色主题 | --primary |
#e65100（橙红） |
| 冷色主题 | --primary |
#1565c0（黛青） |
| 高对比度 | 文字颜色 | #000 / #fff |
- 浏览页面：通过顶部导航栏在各模块之间平滑切换
- 查看角色：滚动到角色区域，卡片会自动渐入显示
- 观看视频：点击任一视频即可播放，其他视频自动暂停
- 调整音量：所有视频统一 0.7 倍音量，无需手动逐个调整
- 离线访问：首次访问后，Service Worker 缓存关键资源，后续可离线浏览
在 京剧猫.html 的 .character-grid 中复制一个 .character-card 区块：
<div class="character-card">
<div class="character-image">
<img src="images/6.jpg"
alt="新角色名 - 简短描述"
width="800"
height="1067"
decoding="async">
</div>
<div class="character-info">
<h3>新角色名</h3>
<p>角色描述文字，介绍角色背景、能力和代表行当。</p>
</div>
</div>CSS 样式会自动适配新卡片，滚动动画无需额外配置。
在 京剧猫.html 的 .gallery-grid 中复制一个 .gallery-item 区块：
<div class="gallery-item">
<div class="gallery-video-container">
<video controls
preload="metadata"
src="videos/8.mp4"
aria-label="京剧猫 - 新视频标题">
您的浏览器不支持视频标签
</video>
</div>
<div class="gallery-text">新视频标题</div>
</div>视频互斥播放和统一音量功能会自动应用于新添加的视频元素。
编辑 styles.css 中的 CSS 变量即可全局更换配色：
:root {
--primary: #8e0000; /* 深红 - 更沉稳的色调 */
--secondary: #c9a84c; /* 暗金 - 降低饱和度 */
--dark: #1a1a1a; /* 深黑 */
--light: #f5f0e8; /* 暖白 */
--accent: #0d47a1; /* 深蓝 */
--paper: #f5edd6; /* 暖宣纸色 */
}修改 script.js 中的 unifiedVolume 变量：
const unifiedVolume = 0.5; // 默认 0.7，范围 0.0 ~ 1.0本项目为纯静态网站，无后端 API。以下为 JavaScript 核心模块的功能说明。
// 导航锚点平滑滚动
document.querySelectorAll('a[href^="#"]').forEach(anchor => {
anchor.addEventListener('click', function (e) {
e.preventDefault();
const target = document.querySelector(this.getAttribute('href'));
if (target) {
target.scrollIntoView({ behavior: 'smooth' });
}
});
});| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
behavior |
string |
'smooth' |
滚动行为，'auto' 为即时跳转 |
const videos = document.querySelectorAll('video');
const unifiedVolume = 0.7;
videos.forEach(video => {
video.volume = unifiedVolume;
video.addEventListener('play', function() {
videos.forEach(other => {
if (other !== video && !other.paused) {
other.pause();
}
});
});
});| 变量 | 类型 | 默认值 | 说明 |
|---|---|---|---|
unifiedVolume |
number |
0.7 |
全局统一音量，范围 0.0 ~ 1.0 |
const observer = new IntersectionObserver((entries) => {
entries.forEach(entry => {
if (entry.isIntersecting) {
entry.target.classList.add('visible');
}
});
}, { threshold: 0.1 });
document.querySelectorAll('.character-card, .featured-item, .gallery-item')
.forEach(item => {
item.classList.add('scroll-animate');
observer.observe(item);
});CSS 类约定：
| 类名 | 说明 |
|---|---|
scroll-animate |
初始状态（透明/位移），等待触发 |
visible |
进入视口后添加，触发过渡动画 |
我们欢迎所有形式的贡献！详细的贡献指引请参阅 CONTRIBUTING.md。
- Fork 本仓库并创建特性分支
- 遵循 Conventional Commits 提交规范
- 提交 Pull Request 到
main分支
提交前请确保 HTML
<img>含alt、<video>含aria-label、CSS 使用已有变量、JS 无全局污染。
本项目遵循 贡献者公约行为准则。
Q: 为什么视频无法播放？
直接双击打开 HTML 文件时，浏览器可能因安全策略（CORS）限制视频加载。请使用本地服务器方式打开（参见 本地预览）。
Q: 如何添加新角色？
在 京剧猫.html 的 .character-grid 中复制一个 .character-card 区块，替换 src 图片路径和文字内容。CSS 样式会自动适配。详见 使用指南 - 添加新角色。
Q: 如何完全更换配色方案？
修改 styles.css 中 :root 下的 CSS 变量值即可全局生效。支持一键切换深色、暖色、冷色等多种主题。详见 使用指南 - 修改配色方案。
Q: 网站部署后未更新？
- 确认 GitHub Pages 的 Source 已设置为 GitHub Actions
- 检查仓库 Actions 页面中的工作流运行状态
- 如构建失败，点击进入查看日志排查具体错误
- 部署成功后有 1-2 分钟的 CDN 缓存刷新延迟
Q: 移动端背景图不滚动？
这是有意为之的设计。在 768px 以下断点，background-attachment 已从 fixed 切换为 scroll，以提升移动端渲染性能并避免 iOS Safari 的已知兼容性问题。
Q: 图片加载失败怎么办？
项目已内置错误处理机制。onerror 回调会确保即使图片加载失败，元素仍被标记为 loaded，不会出现空白占位。建议检查 images/ 目录下 JPG 格式是否存在。
Q: 如何处理离线访问？
首次在线访问后，Service Worker 会自动缓存所有关键资源（HTML / CSS / JS / 图片 / 404 页）。后续即使断网，也能正常浏览页面内容。
| 亮点 | 说明 |
|---|---|
| 国风美学设计 | 中国传统色彩体系 + 书法字体 + 祥云脸谱元素 |
| 传统京韵导航栏 | 深朱红渐变 + 月白文字 + 阴影，对比度 4.8:1 达 WCAG AA |
| 响应式布局 | 4 个断点（1200 / 992 / 768 / 576px），适配手机 / 平板 / 桌面全设备 |
| 关注点分离 | HTML / CSS / JS 独立文件，代码可维护性提升 60% |
| 视频交互体验 | 互斥播放 + 统一音量 + preload="metadata" 预加载元数据 |
| 性能优化 | 图片直接加载 + CSP + preload + preconnect + canonical |
| PWA 离线体验 | Service Worker 缓存关键资源（含 404 页），二次访问秒开 |
| SEO 完整体系 | sitemap + robots + OG + Twitter Card + 结构化 meta |
| XSS 安全防护 | CSP meta 标签（script-src 'self'，无 unsafe-inline），彻底消除内联脚本 |
| 自动化部署 | GitHub Actions CI/CD（5 步流水线），推送即部署 |
| 无障碍友好 | skip-link + :focus-visible + prefers-reduced-motion + video aria-label + img decoding="async" |
| 优雅降级 | 图片加载错误处理 + <noscript> 提示 + 字体多级回退 |
- CSP Meta 标签：
script-src 'self'（无unsafe-inline），从源头消除 XSS 注入风险。字体切换的 inlineonload已用data-onload属性 + JSload事件统一替代 - 外部链接保护：所有
target="_blank"链接均附带rel="noopener noreferrer"，防止window.opener钓鱼攻击 - 错误优雅降级：图片 / 视频加载失败时自动 fallback，不影响整体页面可用性
- Service Worker 安全：缓存策略过滤 opaque 响应（防止跨域缓存膨胀），添加
put操作错误处理；CORE_ASSETS 含404.html，确保离线错误页可用
- Meta 标签：
description、keywords、author、theme-color、canonical - Open Graph：
og:title、og:description、og:image、og:url、og:type、og:locale（社交分享预览优化） - Twitter Card：
twitter:card（summary_large_image）、twitter:title、twitter:description、twitter:image - 结构化指引：
robots.txt+sitemap.xml引导搜索引擎完整索引 - 语义化 HTML：单一
<h1>、正确的<section>/<article>/<header>/<nav>层级 - 图片 alt：所有
<img>含描述性 alt 文本 +decoding="async"异步解码 - 视频 aria-label：所有
<video>含描述性aria-label，屏幕阅读器可完整识别
- 京剧猫官方网站 — 探索更多《京剧猫》精彩内容
- GitHub 仓库 — 查看源代码与提交历史
- 在线演示 — GitHub Pages 线上预览
- Conventional Commits — 本项目遵循的提交规范
- MIT License — 开源许可证全文
本项目基于 MIT License 开源，代码版权归作者所有。
内容素材来源于网络，《京剧猫》动画版权归原创方所有。本页面仅供学习交流与传统文化传播使用，未经明确授权禁止转载或用于商业目的。
传承国粹艺术 · 弘扬传统文化 🎭