chinese-poetry 中文使用教程

一、项目速览

入门 · 1 分钟版

如果你正在找一份结构化的中文古诗词数据集，无论是做诗词生成器、可视化大屏、教育类 App，还是纯粹想用代码“读”一遍唐诗宋词——chinese-poetry/chinese-poetry 是目前 GitHub 上最全的中文诗歌数据库，没有之一。

这个仓库以 JSON 格式 打包了 5.5 万首唐诗、26 万首宋诗、2.1 万首宋词，外加《论语》《诗经》《花间集》等经典文集。作者从互联网上爬取、清洗、整理，最终让这些数据变成一行 fetch 就能调用的资源。

一句话判断：如果你需要一个「拿来就能用」的中文古诗词 JSON 数据集，而不是去爬那些随时可能挂掉的诗歌网站，这个项目值得你花 5 分钟看完。

二、核心功能与架构

进阶 · 推荐细读

项目本身不提供 API 服务或 Web 界面，它更像一个 数据分发仓库——把散落在各个网站的古诗文采集、去重、格式化为标准 JSON，然后通过 GitHub 分发。核心结构只有两层：

数据层：按朝代和文体分目录，每个目录下是若干 JSON 文件。比如 全唐诗 目录下按卷号拆分，每卷一个文件，字段包括 title、author、paragraphs（诗句数组）、notes 等。

元数据层：提供作者索引、词牌名索引等辅助文件，方便按人、按词牌快速查找。

它解决的核心问题是：让非文史专业的开发者，不用面对乱码的 TXT 或扫描版 PDF，直接拿到结构化的诗歌数据。

作者视角补充：如果你是做后端开发的，建议先看 json/ 目录下每个文件的字段定义。我踩过的一个坑是 paragraphs 字段存的是数组而非字符串，直接 join('') 会丢失换行——正确的做法是 join('\n')。

最该用这个项目的人有三类：
- 教育类产品开发者：需要内置诗词库，支持按作者、朝代、关键词搜索
- NLP / 文本生成研究者：需要大量中文古诗语料做训练
- 前端可视化爱好者：想做一个诗词日历、词云图、作者关系图等 Demo

三、动手实践

入门

环境准备

项目不需要安装任何依赖——它只是一个数据仓库。你只需要一个能跑 JavaScript 的环境（浏览器或 Node.js），或者任意一种能解析 JSON 的编程语言。

# 克隆仓库（约 200MB，注意硬盘空间）
git clone https://github.com/chinese-poetry/chinese-poetry.git

# 或者只下载 JSON 目录（更轻量）
# 直接去 GitHub 网页下载 json/ 文件夹即可

最小可运行示例

下面这个例子在浏览器中加载一首唐诗，并打印出诗句。你可以在任意 HTML 文件中运行：

<!DOCTYPE html>
<html>
<body>
<script>
// 从 GitHub raw 地址加载唐诗数据（卷 57 第 1 首）
fetch('https://raw.githubusercontent.com/chinese-poetry/chinese-poetry/master/json/全唐诗/卷057_1.json')
  .then(res => res.json())
  .then(data => {
    // 取第一首诗
    const poem = data[0];
    console.log('标题:', poem.title);
    console.log('作者:', poem.author);
    console.log('诗句:\n' + poem.paragraphs.join('\n'));
  })
  .catch(err => console.error('加载失败', err));
</script>
</body>
</html>

打开浏览器控制台，你会看到类似这样的输出：

标题: 感遇·其一
作者: 张九龄
诗句:
兰叶春葳蕤
桂华秋皎洁
欣欣此生意
自尔为佳节

常见踩坑

跨域问题：如果你在本地 file:// 协议下直接打开 HTML 文件，浏览器会阻止 fetch 请求 GitHub raw 内容。解决方案：用 npx http-server . 起一个本地服务器，或者直接用 VSCode 的 Live Server 插件。
文件编码：所有 JSON 都是 UTF-8 编码，但部分文件包含繁体字。如果你的 Python 脚本读取后显示乱码，记得指定 encoding='utf-8'。
文件体积：全宋诗 目录下单个 JSON 文件可能超过 10MB，浏览器 fetch 会慢。建议在 Node.js 环境中分批读取，或者用 import 动态加载。

四、进阶玩法

深入 · 老手可选

用 Python 做作者作品量统计

这个仓库的数据结构很适合做量化分析。下面这个脚本统计唐诗作者的作品数量，并输出 Top 10：

import json
import os
from collections import Counter

poem_dir = 'json/全唐诗'
author_counter = Counter()

for filename in os.listdir(poem_dir):
    if not filename.endswith('.json'):
        continue
    with open(os.path.join(poem_dir, filename), 'r', encoding='utf-8') as f:
        poems = json.load(f)
        for poem in poems:
            author_counter[poem['author']] += 1

# 输出作品最多的 10 位诗人
for author, count in author_counter.most_common(10):
    print(f'{author}: {count} 首')

运行结果（基于当前数据）大致为：

白居易: 2643 首
杜甫: 1150 首
李白: 1052 首
刘禹锡: 792 首
元稹: 768 首
...

按词牌名搜索宋词

宋词数据中，每首词有 rhythmic（词牌名）字段。你可以用它做分类查询：

import json

with open('json/全宋词/ci.json', 'r', encoding='utf-8') as f:
    all_ci = json.load(f)

# 找出所有《水调歌头》词牌的词
water_songs = [ci for ci in all_ci if ci.get('rhythmic') == '水调歌头']
print(f'水调歌头共 {len(water_songs)} 首')
for ci in water_songs[:3]:
    print(f'{ci["author"]} - {ci["title"]}')

作者视角补充：ci.json 文件比较大（约 15MB），不建议在浏览器中直接全量加载。我在做诗词日历项目时，是按词牌名分片加载的——先加载索引文件，再按需加载对应词牌的数据。

五、判断与建议

进阶 · 推荐细读

应该选它的场景：
- 你需要一份 离线可用、格式统一 的中文古诗词数据集
- 你在做 教育类、文化类、NLP 类 项目，需要基础语料
- 你不想自己爬取诗歌网站（很多站有反爬或速度极慢）
- 你希望数据能被 自由二次分发（MIT 协议）

不该选它的场景：
- 你需要 实时更新的诗歌库（比如每天新增用户投稿）——这个项目是静态数据集，不提供 API
- 你需要 带赏析、注释、翻译 的完整诗歌内容——数据只有原文，没有白话文翻译或赏析
- 你的项目对 数据校验 要求极高（比如学术引用）——数据来自互联网爬取，可能存在少量错别字或作者归属争议
- 你只需要 几十首经典诗 做 Demo——用这个仓库太重量级，不如直接硬编码几首

一句话总结：如果你需要一个 结构化、可编程、离线可用 的中文古诗数据集，chinese-poetry 是目前最好的开源选择；但如果你需要的是带赏析的完整诗歌库，建议另寻商业 API 或百科类网站。

项目信息

项目	值
仓库	chinese-poetry/chinese-poetry
语言	JavaScript
Star	52,617
Fork	10,610
主页	https://awesome-poetry.top/

S.A.O