exercises-dataset 介紹：1324 條健身動作數據集的安裝與使用方法

hasaneyldrm/exercises-dataset 是一個面向健身應用開發者的數據集項目。它把健身動作整理成結構化 JSON，並附帶兩個前端頁面：index.html 用來瀏覽動作，setup.html 用來輔助生成數據庫導入 SQL、API 調用示例和後端開發提示詞。

按照項目 README 的說明，當前數據集覆蓋 1,324 個動作，包含動作名稱、身體部位、器械、目標肌肉、輔助肌羣和分步驟說明。項目適合用來做健身 App 原型、訓練計劃工具、動作搜索頁、推薦系統實驗，或者給大模型生成健身 API 後端時作爲基礎數據。

需要先注意一個細節：倉庫簡介、README、setup.html 和當前 data/exercises.json 的描述並不完全一致。README 明確提示媒體圖片和 GIF 不隨倉庫分發；setup.html 中仍有“images/videos 已包含”的舊描述；當前 raw JSON 裏也可能出現 image、gif_url 這類相對路徑字段。實際接入時應以倉庫當前文件爲準，不要默認圖片和動畫文件一定可用。

適合什麼場景

這個項目不是一個完整健身應用，而是一個可以直接拿來接入應用的數據底座。你可以把它理解成三部分：

data/exercises.json：核心數據文件，應用最終讀取的就是它。
index.html：本地瀏覽器版動作檢索工具，不需要後端。
setup.html：開發者集成嚮導，提供數據庫建表、INSERT SQL 生成、API 示例和 LLM 提示詞。

如果你只是想快速查看數據，打開 index.html 就夠了。如果你要把數據放進自己的產品裏，則應從 data/exercises.json 開始，決定是直接讀取 JSON、導入數據庫，還是生成一層 REST API。

安裝與下載

最簡單的方法是直接克隆倉庫：

1
2


git clone https://github.com/hasaneyldrm/exercises-dataset.git
cd exercises-dataset

倉庫本身主要是靜態文件，不需要 npm install，也沒有必須啓動的後端服務。克隆完成後，目錄大致如下：

1
2
3
4
5
6


exercises-dataset/
├── data/
│   └── exercises.json
├── index.html
├── setup.html
└── README.md

如果只想下載數據文件，也可以直接保存 raw JSON：

1

curl -L -o exercises.json https://raw.githubusercontent.com/hasaneyldrm/exercises-dataset/main/data/exercises.json

Windows PowerShell 可以這樣下載：

1
2
3


Invoke-WebRequest `
  -Uri "https://raw.githubusercontent.com/hasaneyldrm/exercises-dataset/main/data/exercises.json" `
  -OutFile "exercises.json"

下載後建議先確認文件是否能被正常解析：

1

python -m json.tool data/exercises.json > /tmp/exercises.pretty.json

Windows 下可以用：

1

python -m json.tool .\data\exercises.json > .\exercises.pretty.json

如果這一步報錯，說明文件下載不完整，先重新拉取倉庫或重新下載 JSON。

本地打開瀏覽器工具

倉庫的 index.html 是一個純前端瀏覽器，可以直接打開：

1
2
3
4
5


# macOS
open index.html

# Windows PowerShell
Start-Process .\index.html

它適合快速檢查動作數據：搜索動作名稱，按身體部位、器械或目標肌肉篩選，點開卡片查看說明。因爲 README 已說明媒體資源沒有隨倉庫分發，所以瀏覽時如果圖片或 GIF 爲空，不代表數據加載失敗。

如果瀏覽器出於安全策略限制本地文件讀取，可以在倉庫目錄啓動一個臨時靜態服務器：

1

python -m http.server 8000

然後訪問：

1

http://localhost:8000/index.html

Node.js 用戶也可以用：

1

npx serve .

再按命令行提示打開本地地址。

使用 setup.html 生成數據庫和 API 示例

setup.html 是給開發者準備的集成嚮導。打開方式和 index.html 一樣：

1

python -m http.server 8000

然後訪問：

1

http://localhost:8000/setup.html

它的流程主要分三步。

第一步是 Database Setup。頁面可以切換 SQL Server、PostgreSQL、MySQL、SQLite 等數據庫類型，複製對應的 CREATE TABLE 語句，並生成包含 1,324 條動作數據的 INSERT SQL 文件。這個生成過程在瀏覽器本地完成，不需要上傳數據。

第二步是 API Integration。你可以輸入自己的 API base URL，頁面會生成不同語言的調用示例，包括 cURL、JavaScript、Python、C#、Java、PHP、Go。示例接口包括：

1
2
3


GET /exercises/:id
GET /exercises?page=1&limit=20
GET /exercises?category=Strength&body_part=Chest

這裏的接口並不是倉庫已經提供的線上服務，而是建議你在自己的後端裏實現的接口形狀。也就是說，setup.html 幫你整理調用方式，不會替你啓動 API。

第三步是 Ask Your LLM。頁面可以根據框架和數據庫組合生成提示詞，例如 Express.js + PostgreSQL、FastAPI + SQLite、Spring Boot + MySQL、ASP.NET Core + SQL Server、Laravel 或 Gin。你可以把提示詞粘貼到 ChatGPT、Claude 或 Gemini，讓模型根據數據結構生成後端代碼。

直接讀取 JSON

如果你的應用規模不大，直接讀取 data/exercises.json 是最快的方式。Python 示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


import json

with open("data/exercises.json", "r", encoding="utf-8") as f:
    exercises = json.load(f)

print("動作總數:", len(exercises))

chest = [item for item in exercises if item.get("category") == "chest"]
bodyweight = [item for item in exercises if item.get("equipment") == "body weight"]

print("胸部動作:", len(chest))
print("自重動作:", len(bodyweight))

first = exercises[0]
print(first["id"], first["name"])
print(first.get("instructions", {}).get("en"))

Node.js 示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


const exercises = require("./data/exercises.json");

console.log("Total:", exercises.length);

const bodyweight = exercises.filter((item) => item.equipment === "body weight");
const byCategory = exercises.reduce((acc, item) => {
  const key = item.category || "unknown";
  acc[key] = acc[key] || [];
  acc[key].push(item);
  return acc;
}, {});

console.log("Bodyweight:", bodyweight.length);
console.log(Object.keys(byCategory));

前端項目裏可以把 JSON 放到 public/data/exercises.json，再用 fetch 加載：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


async function loadExercises() {
  const res = await fetch("/data/exercises.json");
  if (!res.ok) {
    throw new Error(`Failed to load exercises: ${res.status}`);
  }
  return await res.json();
}

loadExercises().then((exercises) => {
  console.log(exercises.length);
});

如果用 TypeScript，建議先定義一個保守類型。由於 README 與當前 JSON 字段存在差異，image、gif_url、media_id、instruction_steps 這類字段最好寫成可選：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


type Exercise = {
  id: string;
  name: string;
  category?: string;
  body_part?: string;
  equipment?: string;
  target?: string;
  muscle_group?: string;
  secondary_muscles?: string[];
  instructions?: Record<string, string>;
  instruction_steps?: Record<string, string[]>;
  media_id?: string | null;
  image?: string | null;
  gif_url?: string | null;
  created_at?: string;
};

這樣即使倉庫後續調整字段，應用也不容易因爲某個字段缺失直接崩掉。

導入數據庫的做法

正式項目更建議把數據導入數據庫。原因很簡單：分頁、篩選、搜索、後臺編輯和 API 權限控制都更容易做。

一個常見表結構可以這樣設計：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


CREATE TABLE exercises (
  id VARCHAR(32) PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  category VARCHAR(100),
  body_part VARCHAR(100),
  equipment VARCHAR(100),
  target VARCHAR(100),
  muscle_group VARCHAR(100),
  secondary_muscles JSON,
  instructions JSON,
  instruction_steps JSON,
  image VARCHAR(255),
  gif_url VARCHAR(255),
  media_id VARCHAR(100),
  created_at VARCHAR(64)
);

PostgreSQL 可以把 JSON 字段改爲 jsonb：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


CREATE TABLE exercises (
  id text PRIMARY KEY,
  name text NOT NULL,
  category text,
  body_part text,
  equipment text,
  target text,
  muscle_group text,
  secondary_muscles jsonb,
  instructions jsonb,
  instruction_steps jsonb,
  image text,
  gif_url text,
  media_id text,
  created_at text
);

導入流程建議按這個順序做：

用 setup.html 生成對應數據庫的建表 SQL 和 INSERT SQL。
先在本地數據庫或測試庫執行，不要直接導入生產庫。
檢查總行數是否等於 JSON 數組長度。
建索引：至少給 category、body_part、equipment、target 加普通索引。
如果要做關鍵詞搜索，再考慮全文索引或外部搜索服務。

例如 PostgreSQL 可以先加這些索引：

1
2
3
4


CREATE INDEX idx_exercises_category ON exercises(category);
CREATE INDEX idx_exercises_body_part ON exercises(body_part);
CREATE INDEX idx_exercises_equipment ON exercises(equipment);
CREATE INDEX idx_exercises_target ON exercises(target);

後端 API 可以先實現四類接口：

1
2
3
4


GET /exercises
GET /exercises/:id
GET /exercises?category=chest
GET /exercises?equipment=body%20weight

分頁參數建議統一爲：

1

page=1&limit=20

響應結構可以保持穩定：

1
2
3
4
5
6


{
  "items": [],
  "page": 1,
  "limit": 20,
  "total": 1324
}

這樣前端列表、篩選器和無限滾動都比較好接。

媒體資源怎麼處理

README 的提示很重要：不要默認倉庫包含可直接商用的動作圖片和 GIF。它說明基礎數據來自 ExerciseDB v1，媒體資源沒有隨倉庫重新分發，部分記錄會保留媒體引用或相對路徑。

實際項目裏有三種處理方式：

只使用文字數據，不展示圖片和 GIF。
自己準備合法授權的動作圖片或視頻，再用 id 或動作名稱建立映射。
如果你有權使用 ExerciseDB 的媒體資源，再根據相關條款接入對應 CDN 或資源地址。

不要把 image、gif_url 字段直接當作“倉庫裏一定存在的文件”。接入前應檢查：

1
2


ls images
ls videos

如果目錄不存在，應用裏就要給媒體區域做空狀態，或者隱藏圖片和動畫入口。

接入時容易踩的坑

第一，字段可能會變。README 示例和 raw JSON 的字段並非每處都一致，所以代碼裏不要把所有字段都寫成必填。尤其是媒體相關字段和多語言字段，應使用可選讀取。

第二，分類值是英文小寫風格，例如 chest、back、upper legs、body weight。如果你的前端展示中文，應在應用裏做一層映射：

1
2
3
4
5
6
7
8


const categoryLabel = {
  chest: "胸部",
  back: "背部",
  waist: "腰腹",
  "upper legs": "大腿",
  "upper arms": "上臂",
  shoulders: "肩部",
};

第三，動作說明不是醫學建議。它適合作爲產品原型、教學內容和動作檢索數據，但正式健身產品仍應加入安全提示、禁忌說明和專業審覈流程。

第四，不要忽略來源和授權。README 已說明基礎數據來源、媒體不分發原因和權利聲明。商業使用前應重新確認 ExerciseDB、Kaggle re-host 以及該倉庫的使用條款。