每次在12306抢票时，你有没有过这样的好奇：从冰天雪地的漠河站到椰风阵阵的三亚站，全国到底散落着多少座火车站？

我们每天刷着12306的站点列表，按首字母检索目的地，却很少有人深究——这个列表里的车站，是不是就是全国的“全部家底”？今天咱们就顺着12306的线索，揭开火车站数量的小秘密。




## 01 站点数据来源：一个公开的前端 JS 文件

常买火车票的人都知道，12306官网的“国内站点”列表是查询车站的重要入口，输入首字母就能拉出一串相关车站。但这个列表背后，藏着更完整的车站数据。

![](https://blog.siyuan.ink/static/img/5585a7e57c246e6714e2a2a9f8465b90.image.webp)

只要打开浏览器的开发者模式（按下F12即可），在网络请求里就能找到一个特殊的JS文件——`station_name_new_v10092.js`，地址：https://www.12306.cn/index/script/core/common/station\_name\_new\_v10092.js。

![](https://blog.siyuan.ink/static/img/26067fcacc09b23e889ad2959b841114.image.webp)

这个文件里没有复杂的代码，只有一个名为`station_names`的变量，而变量里存储的，正是一长串用特殊符号分隔的车站信息。随便截取一段都能看到规律：

> @bjb|北京北|VAP|beijingbei|bjb|0|0357|北京|||@bjd|北京东|BOP|beijingdong|bjd|1|0357|北京|||@bji|北京|BJP|beijing|bj|2|0357|北京|||

字段依次代表：站名简码、中文站名、电报码、拼音、简拼、序号、区号、所属城市等。其中电报码（如 VAP）是铁路系统内部使用的唯一识别符，具有较高的数据准确性。

从结构上看，这份文件可视为一部标准化的铁路客运车站字典。

## 02 全国到底有多少座火车站

有了结构化数据，下一步就是用Python做数据提取与统计。核心逻辑是“分割-过滤-存储”：先用“@”分割出单条车站记录，过滤掉空值（字符串首尾可能存在空字符），最后统计有效记录数并导出为CSV，方便后续分析。

```python
station_names = 'JS文件里的车站信息字符串'

# 按@分割数据，统计有效车站数量
station_name_list = station_names.strip().split('@')
print(f"车站总数：{len([s for s in station_name_list if s])}")

# 导出为CSV文件
with open('station_name.csv', 'w', encoding='utf-8') as f:
    for station_str in station_name_list:
        if not station_str:
            continue
        station_info = station_str.strip('|').split('|')
        f.write(','.join(station_info)+'\n')
```

运行代码后，答案出来了——**3379座**。这个数字是不是就是全国火车站的“标准答案”？

还真不是。上海的朋友可能有过这样的经历：乘坐S1601次市域铁路动车时，会经过莘庄、春申、新桥、车墩等站点，但在12306的“国内站点”列表里，你根本查不到这些车站的身影。

更有意思的是，12306官网上明明能查到S1601次的完整时刻表，清晰标注着这些“隐形站点”的停靠信息，可它们就是不在车站检索列表里。这就矛盾了——为什么有的车站能卖票却“查无此站”？

![](https://blog.siyuan.ink/static/img/72b4cf3afefda8990b09bc4626ebccda.image.webp)

## 为什么会有“漏网之鱼”？

其实问题出在“统计范围”上。12306的`station_names`变量，本质上是“办理全国铁路跨局旅客运输业务的车站清单”，主要覆盖普速铁路、高铁干线的客运车站。

而像上海S系列这样的市域铁路，定位是“城市通勤铁路”，主要服务于同城或邻近城市的短途出行，很多时候由地方铁路部门运营管理。这类车站的服务范围、票务系统对接方式都和干线铁路不同，因此暂时没有纳入12306的统一站点检索列表，但这并不影响列车售票和运行。

除了市域铁路站点，还有一些小型会让站、乘降所（仅办理少量旅客上下车的站点），以及正在新建、尚未正式开通的车站，也不会出现在这份清单里。如果把这些都算上，全国火车站的实际数量会比3379座多不少。

## 如果让你做一个12306，你会怎么设计数据库

有了结构化的车站字典，可以进一步构建完整的铁路数据体系。后续将从数据库角度出发，设计一个简化版的铁路客运查询系统，包括：

* 车站字典
* 车次信息
* 列车时刻表

使用 PostgreSQL 进行表结构设计，配合 FastAPI 提供查询接口，实现按日期与车次获取停靠站、到发时间等功能。

在此基础上，还可扩展以下应用场景：

* 利用相册中的火车票照片，通过 OCR 与站点字典校准，提高识别准确度
* 根据历史车票构建个人铁路出行记录
* 统计累计乘车时间、经过的城市数量、行程里程等数据

从而为用户的出行留下更完整、可量化的记录。

全国到底有多少座火车站？12306藏着答案，但没那么简单

在票务系统、差旅报销平台或出行类应用中，还原12306官方火车票样式的展示组件是常见需求。本文将详细介绍如何基于 Vue3 Composition API 开发一款高度还原原版、支持自适应布局、动态数据驱动的火车票组件，拆解实现过程中的核心技术亮点与设计思路。



**开源地址在文末！！！**

## 一、组件核心功能亮点

这款火车票组件完全对标12306官方报销凭证样式，具备以下核心特性：

* **像素级还原**：从尺寸比例、颜色搭配、字体大小到布局间距，精准复刻原版火车票视觉效果
* **自适应布局**：自动适配不同容器宽度，保持原始宽高比，支持窗口resize响应
* **动态数据驱动**：通过Props灵活传入车次、站点、时间、乘客等信息，支持多场景复用
* **多优惠标识支持**：支持学生票、儿童票、军残票等多种优惠类型，可传入单个或多个优惠标识
* **导出适配**：支持切换导出模式（取消缩放），满足打印、截图等场景需求
* **Vue3 原生特性**：基于 Composition API 开发，语法简洁、性能优异，支持按需暴露内部API

![](https://blog.siyuan.ink/static/img/6c17f228a27e3c291d79e625a15d735f.G2025.webp)

## 二、技术实现深度解析

### 1. 技术栈基础

* 框架：Vue3（Composition API + `<script setup>` 语法糖）
* 样式：Tailwind CSS（快速实现布局与样式）+ 原生CSS（精准还原细节）
* 核心能力：响应式编程、DOM操作、窗口事件监听、动态样式计算

### 2. 自适应缩放机制：保持比例的关键

原版火车票的宽高比为 `856:540`（基于真实报销凭证尺寸），组件需在不同容器宽度下保持该比例，同时实现自适应缩放。核心实现思路如下：

#### （1）基础尺寸定义

首先定义火车票原始宽高常量，作为缩放计算的基准：

```javascript
// 基础尺寸（复刻12306原版火车票实际尺寸）
const BASE_WIDTH = 856
const BASE_HEIGHT = 540
```

#### （2）容器宽高比约束

通过 `aspect-ratio` 确保外层容器始终保持原始宽高比，避免拉伸变形：

```css
.ticket-wrapper {
  width: 100%;
  position: relative;
  overflow: hidden;
  aspect-ratio: 856 / 540; /* 固定宽高比，适配任何宽度容器 */
}
```

#### （3）动态缩放计算

监听窗口 `resize` 事件和组件挂载事件，通过容器宽度与基准宽度的比值计算缩放比例，再通过 `transform: scale()` 实现自适应：

```javascript
const wrapper = ref(null)
const scale = ref(1)

// 计算缩放比例
function updateScale() {
  if (wrapper.value) {
    const width = wrapper.value.clientWidth
    scale.value = width / BASE_WIDTH // 容器宽度 / 基准宽度 = 缩放比例
  }
}

// 组件挂载时初始化，窗口变化时更新
onMounted(() => {
  updateScale()
  window.addEventListener('resize', updateScale)
})

// 组件卸载时解绑事件，避免内存泄漏
onUnmounted(() => {
  window.removeEventListener('resize', updateScale)
})
```

#### （4）缩放原点控制

通过 `transformOrigin: 'top left'` 确保缩放以左上角为原点，避免布局偏移：

```html
<div
  class="ticket-container"
  :style="{
    transform: exporting ? 'none' : `scale(${scale})`, // 导出时取消缩放
    transformOrigin: 'top left', // 缩放原点：左上角
    width: BASE_WIDTH + 'px',
    height: BASE_HEIGHT + 'px'
  }"
>
```

### 3. Props 设计：灵活且可靠的数据传入

组件通过 `defineProps` 定义输入数据，兼顾灵活性与数据合法性，核心设计如下：

#### （1）支持多类型数据的 Props 定义

针对「优惠类型」这类可能单个或多个的场景，支持 `String` 和 `Array` 两种类型，并通过 `validator` 验证合法性：

```javascript
const props = defineProps({
  // 其他Props...
  discountType: {
    type: [String, Array],
    default: '',
    validator: (value) => {
      const validTypes = ['student', 'discount', 'child', 'elder', 'military', 'disabled', 'group', 'worker-group', 'student-group', '']
      if (Array.isArray(value)) {
        return value.every(item => validTypes.includes(item)) // 数组元素均需合法
      }
      return validTypes.includes(value) // 单个值需合法
    }
  }
})
```

#### （2）动态数据处理

通过 `computed` 对传入数据进行二次处理，适配组件展示需求：

* 时间格式拆分：将 `YYYY-MM-DD HH:mm` 格式拆分为年、月、日、时单独展示
* 优惠文本映射：将 `discountType` 映射为直观的文字标识（如 `student` → 「学」「惠」）

```javascript
// 拆分时间格式
const dateTime = computed(() => {
  return {
    year: props.dateTime.slice(0, 4),
    month: props.dateTime.slice(5, 7),
    day: props.dateTime.slice(8, 10),
    time: props.dateTime.slice(11)
  }
})

// 映射优惠标识文本
const discountTexts = computed(() => {
  const texts = []
  const types = Array.isArray(props.discountType) ? props.discountType : props.discountType ? [props.discountType] : []
  
  types.forEach(type => {
    switch(type) {
      case 'student': texts.push('学', '惠'); break // 学生票显示「学」「惠」双标识
      case 'child': texts.push('儿'); break
      case 'elder': texts.push('老'); break
      case 'military': texts.push('军'); break
      // 其他优惠类型映射...
    }
  })
  return texts
})
```

### 4. 像素级样式还原：复刻原版视觉效果

#### （1）背景效果实现

原版火车票的背景包含「条纹底纹」和「淡化列车图案」，通过多层背景叠加实现：

```css
/* 条纹底纹：使用linear-gradient实现重复纹理 */
.ticket::before {
  content: "";
  position: absolute;
  inset: 0;
  z-index: -1;
  background-color: #e8f3f7;
  background-image: linear-gradient(
    -45deg,
    rgba(180, 200, 220, 0.3) 1px,
    transparent 1px,
    transparent 4px
  );
  background-size: 4px 4px;
}

/* 淡化列车背景图：底部居中显示，低透明度 */
.bgmain .absolute.inset-0.z-\[-2\] {
  background-image: url(/CRH-Dr3OhT7q.jpg);
  background-position: bottom;
  background-repeat: no-repeat;
  background-size: contain;
  opacity: 0.05;
}
```

#### （2）细节样式还原

* 两字站名对齐：通过 `text-align: justify` 实现两字站名均匀分布
* CSS 箭头：无需图片，通过边框组合实现列车方向箭头
* 优惠标识：圆形边框+居中文字，还原原版优惠徽章样式

```css
/* 两字站名对齐 */
.two-char {
  min-width: 145px;
  text-align: justify;
  text-align-last: justify;
}

/* CSS箭头实现 */
.arrow .line {
  height: 4px;
  background-color: #3a5874;
  width: 100%;
}
.arrow .arrow-head {
  position: absolute;
  right: 0;
  top: -7px;
  width: 4px;
  height: 4px;
  border-top: 4px solid #3a5874;
  border-right: 4px solid #3a5874;
  transform: rotate(45deg);
}

/* 优惠标识圆圈 */
.discount-badge {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 36px;
  height: 36px;
  border: 3px solid #1f1d1d;
  border-radius: 50%;
  font-size: 24px;
  line-height: 1;
}
```

### 5. 导出适配：支持打印/截图场景

组件通过 `exporting` 状态控制是否取消缩放，确保导出时为原始尺寸：

```javascript
const exporting = ref(false)
defineExpose({ wrapper, exporting }) // 暴露给父组件控制
```

父组件可通过暴露的 API 切换导出模式：

```javascript
// 父组件中控制导出
const ticketRef = ref(null)
const handleExport = () => {
  ticketRef.value.exporting = true // 取消缩放，使用原始尺寸
  // 执行打印/截图逻辑...
  setTimeout(() => {
    ticketRef.value.exporting = false // 恢复缩放
  }, 100)
}
```

## 三、组件使用指南

### 1. 基础引入

```vue
<template>
  <TrainTicket 
    :fromStation="fromStation"
    :toStation="toStation"
    :trainCode="trainCode"
    :dateTime="dateTime"
    :discountType="['student', 'discount']"
    
  />
</template>

<script setup>
import TrainTicket from './components/TrainTicket.vue'

// 配置数据
const fromStation = '北京西'
const toStation = '深圳北'
const trainCode = 'G71'
const dateTime = '2025-11-15 08:00'
// ...其他配置
</script>
```

### 2. 自定义优惠类型

支持传入单个字符串或数组形式的优惠类型：

```vue

<TrainTicket discountType="child" />


<TrainTicket discountType="['student', 'group']" />
```

## 四、扩展与优化建议

### 1. 功能扩展

* 支持更多优惠类型：在 `discountTexts` 中添加新的类型映射即可
* 二维码动态生成：集成 `qrcode.vue` 等库，根据票据信息动态生成二维码
* 打印功能增强：添加 `@media print` 样式，优化打印效果，隐藏无关元素

### 2. 性能优化

* 图片懒加载：对列车背景图、二维码图片使用懒加载，减少初始加载压力
* 事件防抖：对 `resize` 事件添加防抖处理，避免频繁触发缩放计算

```javascript
import { debounce } from 'lodash'
// 防抖处理：50ms内只触发一次
onMounted(() => {
  updateScale()
  window.addEventListener('resize', debounce(updateScale, 50))
})
```

### 3. 兼容性优化

* 对不支持 `aspect-ratio` 的浏览器，添加降级方案：通过 `padding-bottom` 计算高度

```css
@supports not (aspect-ratio: 856/540) {
  .ticket-wrapper {
    padding-bottom: calc(540 / 856 * 100%); /* 高度 = 宽度 * 540/856 */
  }
}
```


## 五、开源地址

GitHub：[https://github.com/LC044/TimelessTales](https://github.com/LC044/TimelessTales)

Vue3 实现 12306 原版火车票组件：从像素级还原到自适应适配

2025年9月30日之后铁路12306全面施行电子发票，纸质报销凭证不再提供打印服务，但是有很多人都希望打印纸质车票作为留念，我写了一个工具，可以**在线生成电子火车票，可以保存成图片永久保存**。可以使用这个工具做一个票夹，永久留存车票作为纪念。

![](https://blog.lc044.love/static/img/31fbe6b846d371a4751c5e22e412e6c0.image.webp)

“这张去大学的车票，是我第一次独自远行的证明；那张带爸妈去北京的车票，藏着他们看见天安门时的笑容；还有那张说走就走的周末车票，装着青春里的随性与热烈……”

如果你也有收藏纸质火车票的习惯，那最近12306的新政策可能会让你心头一紧——2025年9月30日起，铁路12306将全面施行电子发票，纸质报销凭证的打印服务正式取消。这意味着，以后我们再也拿不到那张印着出发与抵达的实体车票，那些刻在票面上的旅途故事，似乎少了一个看得见、摸得着的载体。

有人说“电子票方便是方便，但总少了点仪式感”；也有人翻着旧票夹感慨“这些车票拼起来，就是我的成长地图”。正是读懂了这份对“旅途回忆”的珍视，我们开发了一款「电子火车票纪念生成工具」——不用再为没票可存遗憾，你的每一段旅程，都能拥有专属的“纪念凭证”。

## 它能帮你做什么？

这款工具专为“留回忆”而生，操作简单到不用看说明书，核心功能精准戳中需求：

* **在线生成秒速完成，信息填写超省心** 只需输入出发地、目的地、日期、座位号等关键信息，点击“生成”按钮，1秒就能得到专属火车票。支持自定义乘客姓名，无论是自己的旅程，还是和家人、朋友的同行记录，都能精准呈现。
* **高清图片永久保存，多场景随心用** 生成的火车票以高清图片格式输出，支持直接保存到手机相册、电脑文件夹，也能一键分享到朋友圈、微博。想打印出来放进票夹？高清画质保证打印后清晰不模糊，完美适配各类尺寸的相框、纪念册。
* **免费无广告，纯粹为回忆服务** 全程不收取任何费用，也没有烦人的弹窗广告。我们深知回忆是纯粹的，所以让工具也保持纯粹——不用注册登录，打开就能用，让每一份旅途记忆都能轻松留存。


![](https://blog.lc044.love/static/img/8ae5f2a4207a203e3d1803d92d5e70ae.image.webp)

## 这些场景，都值得用它记录

或许你会问，什么时候该用这个工具？其实每一段值得铭记的旅程，都值得拥有专属纪念票：

✔️ **毕业旅行**：和室友一起跨过高山大海，用纪念票定格青春里最热闹的同行时光；

✔️ **家庭出游**：带爸妈去看远方的风景，每一张车票都是“陪他们变老”的温暖见证；

✔️ **职场初体验**：第一次去异地出差的车票，记录下为生活奋斗的初心；

✔️ **说走就走的旅行**：那些即兴出发的浪漫，用一张纪念票留住“当时的勇气”；

甚至是小时候和父母出行的模糊记忆，只要记得大概的时间和路线，就能生成一张“复古纪念票”，帮你找回童年的旅途碎片。

## 点开即用

【工具入口】扫描车票二维码，直接进入「电子火车票纪念生成工具」[https://siyuan.ink/tools/trainticket](https://siyuan.ink/tools/trainticket)

![](https://blog.lc044.love/static/img/6c17f228a27e3c291d79e625a15d735f.G2025.webp)

有人说，车票的意义从来不止是“乘车凭证”，它是一段旅程的起点，是一份心情的载体，更是时光里的“坐标”。当12306的纸质票成为过去，我们用技术为回忆“续航”。

## 未来功能预告：让回忆留存更智能

为了给大家带来更贴心的体验，我们的工具还在不断升级打磨，这些实用功能即将上线，敬请期待：

* **自动识别12306订单截图** 无需手动输入信息，只需上传12306的订单截图，工具将自动提取出发地、目的地、时间等关键内容，一键生成对应纪念车票，彻底解放双手，省时又省力。
* **纸质车票照片转电子票** 家里珍藏的旧纸质车票怕磨损？拍照上传即可生成高清电子纪念票，不仅能永久保存，还能修复老旧车票上的模糊字迹，让珍贵回忆重焕清晰。
* **旅程数据统计与出行报告** 自动汇总你用工具生成的所有车票信息，统计出行次数、去过的城市、总里程等数据，生成专属出行报告，用数据勾勒你的旅途足迹，让每一段经历都有迹可循。

## 开源地址

GitHub：[https://github.com/LC044/TimelessTales](https://github.com/LC044/TimelessTales)

12306停供纸质票？别慌！你的旅途回忆，这个工具帮你永久留存

要使用 GitHub Actions 自动打包 Docker 镜像并上传到 Docker Hub，可按以下步骤操作，通过配置工作流文件实现自动化流程：



### **步骤 1：准备工作**

1. **Docker Hub 账号**
    确保拥有 Docker Hub 账号，并创建一个仓库（如 `username/your-image-name`）。
2. **GitHub 仓库**
    将项目代码推送到 GitHub 仓库，确保代码中包含 `Dockerfile`（用于构建镜像）。
3. **配置 Docker Hub 凭据**
    在 GitHub 仓库的 **Settings → Secrets and variables → Actions → New repository secret** 中添加两个密钥：

    * `DOCKER_HUB_USERNAME`：Docker Hub 用户名
    * `DOCKER_HUB_ACCESS_TOKEN`：Docker Hub 访问令牌（在 [Docker Hub 账号设置](https://hub.docker.com/settings/security) 中生成，需勾选 `write` 权限）

### **步骤 2：创建 GitHub Actions 工作流文件**

在 GitHub 仓库中创建工作流配置文件，路径为：
`.github/workflows/docker-build-push.yml`

文件内容如下（可根据需求调整）：

```yaml
name: Build and Push Docker Image

# 触发条件：当推送到 main 分支或创建标签时执行
on:
  push:
    branches: [ "main" ]
    tags: [ "v*.*.*" ]  # 匹配类似 v1.0.0 的标签

jobs:
  build-and-push:
    runs-on: ubuntu-latest  # 使用 Ubuntu 环境
    steps:
      # 步骤 1：拉取 GitHub 仓库代码
      - name: Checkout code
        uses: actions/checkout@v4

      # 步骤 2：设置 Docker 构建环境
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      # 步骤 3：登录 Docker Hub
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_HUB_USERNAME }}
          password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}

      # 步骤 4：提取镜像标签（支持分支和标签触发）
      - name: Extract metadata (tags, labels)
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ secrets.DOCKER_HUB_USERNAME }}/your-image-name  # 替换为你的 Docker Hub 仓库名
          tags: |
            type=ref,event=branch  # 分支触发时，标签为分支名（如 main）
            type=semver,pattern={{version}}  # 标签触发时，标签为版本号（如 v1.0.0 → 1.0.0）
            type=semver,pattern={{major}}.{{minor}}  # 标签触发时，额外添加主版本标签（如 1.0）

      # 步骤 5：构建并推送 Docker 镜像
      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          context: .  # Dockerfile 所在目录（当前目录）
          push: true  # 推送镜像到 Docker Hub
          tags: ${{ steps.meta.outputs.tags }}  # 使用步骤 4 生成的标签
          labels: ${{ steps.meta.outputs.labels }}  # 附加元数据标签
```

#### **关键配置说明**

1. **触发条件（**`on` **）** 
    示例中配置了推送到 `main` 分支或创建 `v*.*.*` 格式的标签时触发工作流，可根据需求修改（如添加 `pull_request` 触发）。
2. **镜像标签（**`tags`**）** 
    通过 `docker/metadata-action` 自动生成标签：

    * 推送到 `main` 分支时，标签为 `main`（方便测试环境使用）。
    * 推送标签 `v1.0.0` 时，生成标签 `1.0.0` 和 `1.0`（方便生产环境指定版本）。
3. **构建上下文（**`context` **）** 
    默认为当前目录（`.`），若 `Dockerfile` 在子目录（如 `./docker`），需修改为 `context: ./docker` 并通过 `file: ./docker/Dockerfile` 指定路径。

### **步骤 3：测试工作流**

1. 将配置文件提交到 GitHub 仓库的 `main` 分支。
2. 触发工作流：

    * 推送代码到 `main` 分支，工作流会自动运行并推送 `main` 标签的镜像。
    * 创建并推送标签（如 `git tag v1.0.0 && git push origin v1.0.0`），工作流会推送 `1.0.0` 和 `1.0` 标签的镜像。
3. 在 GitHub 仓库的 **Actions** 标签页中查看工作流运行状态，成功后可在 Docker Hub 仓库中看到推送的镜像。

#### 注意：如果有多个镜像也可使用docker-compose构建

例如，项目根目录下有个`docker-composr.yml`文件，其作用是从子目录里分别构建两个镜像siyuan044/timelesstales-backend和siyuan044/timelesstales-frontend

```yml
version: '3.8'

services:
  backend:
    build: ./package/server
    # 用环境变量 ${TAG} 动态指定版本（默认 fallback 到 v0.1.0）
    image: siyuan044/timelesstales-backend:${TAG:-v0.1.0}
    restart: always
    expose: [ "8000" ]
    networks: [ app-network ]
    volumes: [ "./package/server/data:/app/data" ]

  frontend:
    build: ./package/website
    image: siyuan044/timelesstales-frontend:${TAG:-v0.1.0}
    restart: always
    ports: [ "8081:80" ]
    depends_on: [ backend ]
    networks: [ app-network ]

networks:
  app-network:
    driver: bridge
```

此时可以使用 docker compose build命令构建镜像（注意部署docker-compose build）

```yml
      # 构建镜像（基于基础标签）
      - name: Build images with docker compose
        run: |
          TAG=${{ env.BASE_TAG }} docker compose build
```

### 补充：自动更新latest标签

当创建新的 Tag 时（如 `v1.0.1`），希望同时将 `latest` 标签指向该最新版本的镜像，可以在推送时额外添加 `latest` 标签。以下是具体实现方案，确保每次发布新 Tag 时，`latest` 会自动更新为该版本。

#### **核心思路**

1. 当工作流由 **Tag 触发** 时（如 `v1.0.1`），除了推送 `1.0.1` 标签的镜像，额外推送 `latest` 标签的镜像。
2. 当由 **分支触发** 时（如 `main`），仅推送分支标签（不影响 `latest`，避免开发版本覆盖正式版）。

#### **修改工作流配置**

更新 `.github/workflows/docker-compose-build-push.yml`，重点调整 **镜像标签生成** 和 **推送逻辑**：

```yml
name: Build and Push Multi Docker Images with Compose

on:
  push:
    branches: [ "main" ]
    tags: [ "v*.*.*" ]

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Docker
        uses: docker/setup-buildx-action@v3

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_HUB_USERNAME }}
          password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}

      # 步骤：生成基础标签和额外标签（如 latest）
      - name: Determine image tags
        id: set-tags
        run: |
          # 基础标签（分支名或 Tag 版本）
          if [[ $GITHUB_REF == refs/tags/* ]]; then
            BASE_TAG=${GITHUB_REF#refs/tags/v}  # 如 v1.0.1 → 1.0.1
            EXTRA_TAGS="latest"  # Tag 触发时，额外添加 latest 标签
          else
            BASE_TAG=${GITHUB_REF#refs/heads/}  # 如 main 分支 → main
            EXTRA_TAGS=""  # 分支触发时，不添加 latest
          fi
          # 组合所有标签（用逗号分隔，供后续推送）
          ALL_TAGS="$BASE_TAG"
          if [ -n "$EXTRA_TAGS" ]; then
            ALL_TAGS="$BASE_TAG,$EXTRA_TAGS"
          fi
          # 输出环境变量（后端和前端镜像名相同，仅标签变化）
          echo "BASE_TAG=$BASE_TAG" >> $GITHUB_ENV
          echo "ALL_TAGS=$ALL_TAGS" >> $GITHUB_ENV

      # 构建镜像（基于基础标签）
      - name: Build images with docker compose
        run: |
          TAG=${{ env.BASE_TAG }} docker compose build

      # 推送镜像（包含所有标签：基础标签 + latest（若有））
      - name: Push backend images
        run: |
          # 拆分标签并逐个推送（或用 docker tag 批量处理）
          IFS=',' read -ra TAGS <<< "${{ env.ALL_TAGS }}"
          for TAG in "${TAGS[@]}"; do
            # 先给镜像打多标签，再推送
            docker tag ${{ secrets.DOCKER_HUB_USERNAME }}/timelesstales-backend:${{ env.BASE_TAG }} ${{ secrets.DOCKER_HUB_USERNAME }}/timelesstales-backend:$TAG
            docker push ${{ secrets.DOCKER_HUB_USERNAME }}/timelesstales-backend:$TAG
          done

      - name: Push frontend images
        run: |
          IFS=',' read -ra TAGS <<< "${{ env.ALL_TAGS }}"
          for TAG in "${TAGS[@]}"; do
            docker tag ${{ secrets.DOCKER_HUB_USERNAME }}/timelesstales-frontend:${{ env.BASE_TAG }} ${{ secrets.DOCKER_HUB_USERNAME }}/timelesstales-frontend:$TAG
            docker push ${{ secrets.DOCKER_HUB_USERNAME }}/timelesstales-frontend:$TAG
          done
```

告别手动打包！GitHub Actions 帮你自动推送 Docker 镜像到 Docker Hub

对于 C++ 新手来说，容器是编写高效代码的基础工具。容器本质上是**用于存储和管理数据的类模板**，C++ 标准库（STL）提供了多种容器，每种容器都有独特的底层结构和适用场景。本文将按类别介绍常用容器，包括初始化、遍历和核心操作，帮助新手快速上手。



## 一、容器的分类

STL 容器主要分为四大类，新手需先明确各类容器的核心特点：

| 类别           | 代表容器                             | 核心特点                                    | 适用场景                                 |
| ---------------- | -------------------------------------- | --------------------------------------------- | ------------------------------------------ |
| 序列式容器     | vector、list、deque                  | 数据按插入顺序存储，可通过索引 / 迭代器访问 | 需按顺序存储、频繁访问或修改数据         |
| 关联式容器     | map、set、multimap、multiset         | 数据自动排序（基于红黑树），通过键值访问    | 需快速查找、排序或去重数据               |
| 无序关联式容器 | unordered\_map、unordered\_set | 数据无序存储（基于哈希表），通过键值访问    | 需超快速查找（O (1) 复杂度），不关心排序 |
| 适配器容器     | stack、queue、priority\_queue     | 基于其他容器封装，提供特定操作接口          | 需特定数据结构（如栈、队列）的场景       |

## 二、序列式容器：按顺序存储数据

序列式容器是新手最易理解的类型，数据存储顺序与插入顺序一致，支持直接访问。

### 1. vector：动态数组（最常用）

**底层结构**：动态数组（内存连续），支持快速随机访问，但插入 / 删除尾部外元素效率低。

**核心优势**：访问速度快（O (1)），内存连续，适合频繁读操作。

#### （1）初始化方式

```c++
#include <vector>
using namespace std;

// 1. 空vector
vector<int> v1;

// 2. 初始化n个默认值（int默认0，string默认空）
vector<int> v2(5);       // 存储：[0,0,0,0,0]
vector<string> v3(3);    // 存储：["","",""]

// 3. 初始化n个指定值
vector<int> v4(4, 10);   // 存储：[10,10,10,10]

// 4. 用数组/其他容器初始化
int arr[] = {1,2,3,4};
vector<int> v5(arr, arr+4);          // 用数组初始化（左闭右开）
vector<int> v6(v5.begin(), v5.end());// 用其他vector初始化
vector<int> v7 = {1,2,3,4,5};        // C++11后支持列表初始化（推荐）
```

#### （2）遍历方式

```c++
// 1. 下标访问（类似数组，仅vector和deque支持）
for (int i = 0; i < v7.size(); i++) {
    cout << v7[i] << " ";  // 输出：1 2 3 4 5
}

// 2. 迭代器（通用遍历方式，所有容器支持）
vector<int>::iterator it;  // 普通迭代器（可修改数据）
for (it = v7.begin(); it != v7.end(); it++) {
    *it += 1;              // 修改数据（每个元素+1）
    cout << *it << " ";    // 输出：2 3 4 5 6
}

// 3. 范围for循环（C++11后，简洁推荐）
for (int num : v7) {
    cout << num << " ";    // 输出：2 3 4 5 6
}
// 若需修改数据，加引用：for (int& num : v7) { num +=1; }
```

#### （3）常用方法

| 方法             | 功能                        | 示例                                           |
| ------------------ | ----------------------------- | ------------------------------------------------ |
| size()           | 返回元素个数                | int len \= v7.size();（结果为 5）           |
| push\_back(x) | 在尾部添加元素 x            | v7.push\_back(6);（v7 变为 [2,3,4,5,6,6]）  |
| pop\_back()   | 删除尾部元素（无返回）      | v7.pop\_back();（v7 变回 [2,3,4,5,6]）      |
| empty()          | 判断是否为空（空返回 true） | if (v7.empty()) { ... }                        |
| clear()          | 清空所有元素                | v7.clear();（size 变为 0，内存不释放）         |
| insert(pos, x)   | 在迭代器 pos 位置插入 x     | v7.insert(v7.begin()+2, 9);（在第 3 位插入 9） |
| erase(pos)       | 删除迭代器 pos 位置元素     | v7.erase(v7.begin()+2);（删除第 3 位元素）     |

### 2. list：双向链表

**底层结构**：双向链表（内存不连续），插入 / 删除效率高（O (1)），但不支持随机访问。

**核心优势**：适合频繁在中间插入 / 删除数据（如链表操作）。

#### （1）初始化与 vector 类似

```c++
#include <list>
list<int> l1;                  // 空list
list<int> l2(3, 5);            // 3个5：[5,5,5]
list<int> l3 = {1,2,3,4};      // 列表初始化
```

#### （2）遍历：仅支持迭代器和范围 for

```c++
// 不支持下标访问！必须用迭代器
for (list<int>::iterator it = l3.begin(); it != l3.end(); it++) {
    cout << *it << " ";  // 输出：1 2 3 4
}

// 范围for（推荐）
for (int num : l3) {
    cout << num << " ";
}
```

#### （3）独特常用方法

除size()、empty()、clear()外，list 有链表专属方法：

| 方法              | 功能                        | 示例                                         |
| ------------------- | ----------------------------- | ---------------------------------------------- |
| push\_front(x) | 在头部添加 x                | l3.push\_front(0);（l3 变为 [0,1,2,3,4]） |
| pop\_front()   | 删除头部元素                | l3.pop\_front();（l3 变回 [1,2,3,4]）     |
| insert(pos, x)    | 在 pos 位置插入 x（效率高） | l3.insert(l3.begin()+1, 9);（无需移动元素）  |
| remove(x)         | 删除所有值为 x 的元素       | l3.remove(2);（删除所有 2）                  |

### 3. deque：双端队列

**底层结构**：分段连续内存（类似 “动态数组的数组”），支持头部和尾部快速操作。

**核心优势**：兼顾 vector 的随机访问和 list 的首尾操作效率，适合 “队列” 场景。

#### 关键特点

* 支持下标访问（deque[0]）和迭代器遍历；
* 常用方法：push\_front(x)、push\_back(x)、pop\_front()、pop\_back()（首尾操作均为 O (1)）；
* 初始化和遍历与 vector 完全一致，新手可先类比 vector 学习。

## 三、关联式容器：自动排序的 “字典”

关联式容器基于**红黑树**实现，数据会自动按 “键值” 排序，支持快速查找（O (log n)）。核心是 “键（key）” 和 “值（value）” 的映射关系。

### 1. map：键值对映射（键唯一）

**核心特点**：每个元素是pair\<key, value\>（键值对），键不能重复，自动按键排序（默认升序）。

**适用场景**：需要 “字典” 功能（如姓名→成绩、ID→信息）。

#### （1）初始化方式

```c++
#include <map>
using namespace std;

// 1. 空map（键int，值string）
map<int, string> m1;

// 2. 插入键值对（3种方式）
m1[1] = "Alice";          // 下标插入（键1对应值Alice）
m1.insert(pair<int, string>(2, "Bob"));  // pair插入
m1.insert({3, "Charlie"});               // C++11列表插入（推荐）

// 3. 直接初始化
map<int, string> m2 = {
    {1, "Alice"},
    {2, "Bob"},
    {3, "Charlie"}
};
```

#### （2）遍历方式

```c++
// 1. 迭代器（需访问pair的first和second）
map<int, string>::iterator it;
for (it = m2.begin(); it != m2.end(); it++) {
    // it->first是键，it->second是值
    cout << "ID:" << it->first << " Name:" << it->second << endl;
}

// 2. 范围for（推荐，用auto简化类型）
for (auto& pair : m2) {  // auto自动识别为pair<int, string>
    cout << "ID:" << pair.first << " Name:" << pair.second << endl;
}
```

#### （3）常用方法

| 方法       | 功能                                   | 示例                                               |
| ------------ | ---------------------------------------- | ---------------------------------------------------- |
| size()     | 返回键值对个数                         | int len \= m2.size();（结果为 3）               |
| find(key)  | 查找键为 key 的元素，返回迭代器        | auto it \= m2.find(2);（找到返回对应迭代器）    |
| count(key) | 统计键为 key 的个数（map 中仅 0 或 1） | if (m2.count(2) \> 0) { ... }（判断键是否存在） |
| erase(key) | 删除键为 key 的元素                    | m2.erase(2);（删除 ID\=2 的键值对）             |
| clear()    | 清空所有元素                           | m2.clear();                                        |

### 2. set：仅存储键（键唯一且排序）

**核心特点**：仅存储 “键”（无值），键唯一且自动排序，本质是 “去重 + 排序” 的集合。

**适用场景**：需要去重或排序的数据（如统计不重复的成绩）。

#### 关键操作（类比 map）

```c++
#include <set>
set<int> s = {3,1,2,3};  // 初始化，自动去重并排序为[1,2,3]

// 遍历
for (int num : s) {
    cout << num << " ";  // 输出：1 2 3
}

// 常用方法
s.insert(4);             // 插入4（变为[1,2,3,4]）
s.erase(2);              // 删除2（变为[1,3,4]）
if (s.find(3) != s.end()) {  // 查找3是否存在
    cout << "3 exists";
}
```

### 3. multimap/multiset：允许键重复

* **multimap**：键可重复，其他与 map 一致（如按键排序）；
* **multiset**：键可重复，其他与 set 一致；
* 区别：count(key)可能返回大于 1 的值，find(key)返回第一个匹配的键。

## 四、无序关联式容器：快速查找的 “哈希表”

无序关联式容器基于**哈希表**实现，数据无序存储，但查找效率极高（平均 O (1)），适合 “只查不改” 或 “频繁查找” 场景。

核心容器：unordered\_map和unordered\_set，用法与map/set完全一致，仅两点区别：

1. 数据无序（遍历顺序与插入顺序无关）；
2. 不支持按键排序相关操作（如lower\_bound）。

示例（unordered\_map）：

```c++
#include <unordered_map>
unordered_map<int, string> um = {
    {1, "Alice"},
    {2, "Bob"}
};

// 遍历（顺序不确定，可能是2→1或1→2）
for (auto& pair : um) {
    cout << pair.first << ":" << pair.second << endl;
}

// 查找效率比map高（哈希表直接定位）
auto it = um.find(1);  // 平均O(1)时间
```

## 五、适配器容器：封装后的 “专用工具”

适配器容器不直接存储数据，而是基于其他容器（如 vector、deque）封装，提供特定操作接口，新手需掌握核心用法。

### 1. stack：栈（先进后出）

**底层依赖**：默认基于 deque，支持push（入栈）、pop（出栈）、top（取栈顶）。

```c++
#include <stack>
stack<int> st;

st.push(1);  // 入栈：[1]
st.push(2);  // 入栈：[1,2]
cout << st.top();  // 取栈顶：2
st.pop();          // 出栈：[1]
cout << st.size(); // 大小：1
```

### 2. queue：队列（先进先出）

**底层依赖**：默认基于 deque，支持push（入队）、pop（出队）、front（取队首）。

```c++
#include <queue>
queue<int> q;

q.push(1);  // 入队：[1]
q.push(2);  // 入队：[1,2]
cout << q.front();  // 取队首：1
q.pop();            // 出队：[2]
```

### 3. priority\_queue：优先队列（自动排序）

**底层依赖**：默认基于 vector，数据自动按 “大顶堆” 排序（队首是最大值）。

```c++
#include <queue>
priority_queue<int> pq;

pq.push(3);  // 入队：[3]
pq.push(1);  // 入队后排序：[3,1]
pq.push(2);  // 入队后排序：[3,2,1]
cout << pq.top();  // 取最大值：3
pq.pop();          // 出队后排序：[2,1]
```

## 六、新手选择容器的核心原则

1. **频繁访问数据**：选 vector（随机访问快）；
2. **频繁插入 / 删除中间元素**：选 list（链表无需移动数据）；
3. **需要队列 / 栈操作**：选 queue/stack（适配器简单易用）；
4. **需要字典功能（键值对）** ：

* 需排序：选 map；
* 不需排序但要快查：选 unordered\_map；

5. **需要去重**：

* 需排序：选 set；
* 不需排序但要快查：选 unordered\_set。

通过以上内容，新手可掌握 C++ 常用容器的核心用法。建议结合实际代码练习（如用 vector 存储学生成绩、用 map 实现字典查询），逐步熟悉各类容器的适用场景，为后续学习算法和数据结构打下基础。

C++ 容器入门：从初始化到常用操作全解析

👨🏻‍💻这是一个充满知识💬的链接，快点进来看看你的好友给你分享了什么干货吧❣️