# swordshadow

**Repository Path**: eagling/swordshadow

## Basic Information

- **Project Name**: swordshadow
- **Description**: 踏歌剑影舞公会宣传网站
- **Primary Language**: HTML
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-26
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 踏歌剑影舞 · 公会官网

> 仗剑踏歌，影舞天涯

魔兽世界 **时光服**（四区 · 联盟）公会「踏歌剑影舞」的宣传站点。单页应用，主页包含歌舞藏锋、江湖足迹相册、远征之路（版本路线）、江湖藏卷（专题入口）与英雄帖（招募，含活动时间）等章节，配有粒子背景、滚动进度条、章节渐入等动效。子页：团本志 `/raids`（含团本/BOSS 独立详情页）、周边 `/merch`、百宝阁 `/vault`（成员共建的攻略、心得、插件推荐与公会制度）、相册 `/photos`。

## 技术栈

- [Vue 3](https://vuejs.org/)（`<script setup>` 组合式 API）
- [Vite 4](https://vitejs.dev/)
- 纯 CSS 样式（`src/styles/main.css`），无 UI 框架依赖
- UI 标准见 [docs/ui-style-guide.md](docs/ui-style-guide.md)（改样式/加页面前必读）
- 字体：Ma Shan Zheng / Noto Serif SC / Cinzel（Google Fonts，`index.html` 引入）

## 环境要求

- Node.js **>= 16**（已在 Node 16.17 下验证 dev / build 通过；Vite 5 需 Node 18+，故本项目锁定 Vite 4）

## 快速开始

```bash
# 安装依赖
npm install

# 启动开发服务器（默认端口 5173）
npm run dev

# 构建生产产物（输出到 dist/）
npm run build

# 本地预览构建产物
npm run preview
```

## 部署（Nginx）

站点使用 history 路由模式，直接刷新 `/raids` 等子路径需要 Nginx 把未匹配路径回退到 `index.html`：

```nginx
server {
    listen 80;
    server_name 你的域名;
    root /path/to/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}
```

### 云服务器独立部署（HTTPS）

仓库自带完整主配置 `nginx-conf/tgwow-nginx.conf`（含 HTTP 跳 HTTPS、SSL、gzip、静态缓存与路由回退），部署步骤：

```bash
# 服务器上：构建产物放到 /data/workspace/swordshadow/dist，并建好日志目录
mkdir -p /data/workspace/swordshadow/logs

# 修改配置中的三处 TODO：域名、/etc/nginx/ssl/ 下的 pem/key 实际文件名
# 检查并启动（需 sudo：读 SSL 私钥、绑定 80/443 特权端口）
sudo nginx -t -c /data/workspace/swordshadow/nginx-conf/tgwow-nginx.conf
sudo nginx -c /data/workspace/swordshadow/nginx-conf/tgwow-nginx.conf
```

同时把 `index.html` 里的 `og:url` 改为正式域名（预渲染分享页在构建时读取它）。

## 上线前配置

- **分享卡片（OG）**：`index.html` 中 `og:url` / `og:image` 填写实际域名；封面图为 `public/assets/share-cover.jpg`
- **访问统计（百度统计）**：在 [tongji.baidu.com](https://tongji.baidu.com) 注册站点后，把站点 ID 填入 `src/utils/analytics.js` 的 `BAIDU_SITE_ID`，留空则不加载统计脚本；路由切换的 PV 已自动上报

## 团本分享页

团本详情是独立页面（无弹窗）：`/raids/<code>`（如 `/raids/MC`）；每个 BOSS 也是独立地址 `/raids/<code>/<slug>`（slug 为 `bosses.js` 中每个 BOSS 的英文标识，如 `/raids/MC/ragnaros`），打开即滚动到位。详情页头部可复制团本链接，每个 BOSS 卡片有「分享」按钮复制 BOSS 链接；宽屏下右侧有 BOSS 侧边导航，窄屏/移动端为顶栏下方的吸顶横滑导航条，点击定位 BOSS 并在地址栏同步 `#boss-<slug>` 锚点（如 `/raids/MC#boss-ragnaros`）；滚动页面时锚点也会跟随当前视口中的 BOSS 自动更新（滚动回页头区域则清除锚点），带锚点的链接打开同样能定位。旧版数字序号链接（`/raids/MC/10`）会自动跳转到对应 slug 地址。

- **微信内分享**：`src/utils/shareMeta.js` 在路由进入时更新当前页的 title 与 og 标签，微信内置浏览器分享读取当前 DOM，能看到团本/BOSS 专属标题与简介
- **QQ / 微博 / 搜索引擎**：这类爬虫只读服务端返回的静态 HTML，由 `scripts/prerender-raids.mjs` 在 `npm run build` 后生成全部静态分享页（`/raids`、`/merch`、`/vault`、`/photos` 等栏目页 + 21 个团本 + 全部 BOSS + 全部百宝阁文章，内容仍是同一 SPA）。域名取自 `index.html` 的 `og:url`；`og:image` 用各团本的场景图——脚本经 Vite manifest 找到哈希产物并复制为稳定路径 `assets/og/<code>.jpg`（需在 `vite.config.js` 开启 `build.manifest`）；栏目页的 title/desc 与 `src/router.js` 的 `meta.share` 保持同步；新增团本只要保持 `raids.js` 中 `{ code, name, …, desc }` 的写法即自动覆盖；新增 BOSS 需在 `bosses.js` 中填写 `slug`（英文小写，团本内唯一），缺失会在构建时告警并跳过；百宝阁文章页 `/vault/<id>` 的分享卡片自动取文章的标题、作者与概要

## 项目结构

```
├── index.html              # 入口 HTML（标题、描述、OG 分享卡片、Google Fonts）
├── vite.config.js          # Vite 配置（base: '/'，history 路由）
├── scripts/
│   └── prerender-raids.mjs # 构建后为每个团本/栏目页生成静态分享页 dist/raids/<code>/ 等
└── src/
    ├── main.js             # 应用入口（接入访问统计）
    ├── App.vue             # 页面骨架；滚动进度条、回顶按钮、章节渐入
    ├── router.js           # 路由（主页 + 各子页；meta.share 为分享卡片信息）
    ├── utils/
    │   ├── analytics.js    # 百度统计（填站点 ID 启用，SPA 路由 PV 自动上报）
    │   ├── shareMeta.js    # 动态更新 title / og（微信内分享卡片）
    │   └── reveal.js       # 章节渐入
    ├── styles/
    │   └── main.css        # 全局样式与设计变量
    ├── assets/
    │   ├── hero_light.jpg / tage_light.jpg / jianying_light.jpg  # 首屏与插画
    │   ├── logo/           # 公会徽标（导航 / 首屏 / 页脚）
    │   ├── road/           # 远征之路卡片背景（now / next / far）
    │   ├── raid/           # 团本场景图（按团本代号命名）
    │   ├── class/          # 职业插画
    │   ├── roles/          # 职责主题图（坦克 / 治疗 / 输出）
    │   ├── players/        # 江湖足迹相册（放公会合影）
    │   ├── merch/          # 周边实拍/设计图
    │   └── vault/          # 百宝阁文章配图（按文章 id 分目录）
    ├── data/
    │   ├── guild.js        # 主页文案与数据（改内容只动这里）
    │   ├── raids.js        # 团本子页数据（阶段 / 团本 / 阵容配置）
    │   ├── bosses.js       # 各团本 BOSS 名录与技能要点
    │   ├── vault.js        # 百宝阁文章与分类（投稿只动这里）
    │   ├── merch.js        # 周边子页数据
    │   └── solarTerms.js   # 二十四节气主题（节气换色与粒子）
    ├── views/
    │   ├── HomeView.vue        # 主页（各章节组合）
    │   ├── RaidsView.vue       # 团本志总览
    │   ├── RaidDetailView.vue  # 团本/BOSS 详情（可分享）
    │   ├── VaultView.vue       # 百宝阁列表
    │   ├── VaultArticleView.vue# 百宝阁文章详情（可分享）
    │   ├── MerchView.vue       # 江湖周边
    │   └── PhotoScrollView.vue # 相册（Coverflow 卷轴）
    └── components/
        ├── common/         # 通用构件（SectionHead / ImageModal / TiltFrame）
        ├── home/           # 主页各章节（SiteHero / SpiritSection / PhotoGrid /
        │                   #  JourneySection / PortalSection / JoinPoster）
        ├── layout/         # 布局（SiteNav / SiteFooter / HomeSideNav /
        │                   #  ParticleCanvas / SvgSprite / TermDecor / TermSeal）
        └── raids/          # 团本相关（RaidBlock）
```

## 内容维护

主页的所有文案与数据（公会名、服务器信息、章节文案、活动时间、招募联系方式等）集中在 **`src/data/guild.js`**，按章节分块并有注释，修改内容无需触碰组件代码。子页内容各有专属数据文件：团本与阵容在 `src/data/raids.js`、BOSS 名录在 `src/data/bosses.js`、周边在 `src/data/merch.js`、节气主题在 `src/data/solarTerms.js`、百宝阁在 `src/data/vault.js`。

### 相册上墙

1. 把公会合影放入 `src/assets/players/`（支持 png / jpg / jpeg / webp）
2. 在 `src/data/guild.js` 的 `photos` 数组登记文件名：`{ img: photo('xxx.jpg'), desc: '照片说明' }`
   - 目录下的图片由 `import.meta.glob` 自动加载，无需手动 import
   - 文件不存在或 `img` 为 `null` 时显示「此处虚位」占位相框
   - `desc` 为照片底部的说明文字，留空则不显示

### 百宝阁（成员投稿）

1. 在 `src/data/vault.js` 的 `vaultArticles` 数组追加文章，字段与正文块写法见文件顶部注释
2. 配图按文章分目录存放：`src/assets/vault/<文章id>/`（支持 png / jpg / jpeg / webp），正文用 `{ shots: [{ img: '<文章id>/文件名', caption: '说明' }] }` 引用
3. 需要新分类时在 `vaultCategories` 加一行 `{ id, label }`，页面筛选自动出现
4. 每篇文章有独立分享页 `/vault/<id>`：微信内分享的标题/简介/封面由 `VaultArticleView` 动态设置（`标题 · 作者 · 百宝阁`），构建时预渲染脚本同步生成静态分享页，均取自文章的 `title` / `author` / `summary` / `cover`；`cover` 填本文配图目录里的一张代表性截图，脚本会复制为稳定路径 `assets/og/vault/<id>.<ext>`，留空则回退站点通用封面

### 版权说明

如在本站使用游戏截图，请仅用于非公开展示或遵循暴雪粉丝内容政策。

## 许可证

MIT