📋 部署检查清单 - 访问者位置地图
📋 部署检查清单 - 访问者位置地图
🎯 部署前准备
第一步：收集必要信息
- 已有GitHub账户
- 已有Vercel账户
- 已知GitHub用户名：
YultheConkor - 已连接GitHub和Vercel（自动登录）
🔗 第二步：创建GitHub Gist
2.1 打开Gist服务
URL: https://gist.github.com
操作：点击右上角 + 按钮，选择 "New Gist"
2.2 填写Gist内容
文件名：visitors-data.json（可选，会自动生成）
内容：
{
"visitors": [],
"updated_at": "2025-10-22T00:00:00Z"
}
2.3 设置权限
选择：Public（公开）
点击：Create public gist
2.4 记录Gist信息
✅ 记录Gist URL中的ID
例如：https://gist.github.com/YultheConkor/abc123def456
ID是：abc123def456
✅ 点击"Raw"按钮，复制Raw URL
例如：https://gist.githubusercontent.com/YultheConkor/abc123def456/raw/...
检查点：
- Gist已创建并设为Public
- Gist ID已记录
- Raw URL已复制
🔐 第三步：生成GitHub Personal Access Token
3.1 打开Token页面
URL: https://github.com/settings/tokens/new
3.2 配置Token权限
Token name: yultheconkor-visitor-tracker
Expiration: 90 days （或Custom，选择更长时间）
Description: (可选) Visitor tracking Gist API access
3.3 选择权限范围
向下滚动到 Scopes 部分
☑️ 勾选：gist
（自动勾选的其他权限可以忽略，仅需gist）
3.4 生成并保存Token
点击：Generate token
⚠️ 立即复制Token（只显示一次！）
保存在安全位置（如密码管理器）
检查点：
- Token已生成
- Token已复制和保存
- Token权限包括gist
🚀 第四步：配置Vercel环境变量
4.1 打开Vercel Dashboard
URL: https://vercel.com/dashboard
登录你的Vercel账户
4.2 选择项目
找到：yultheconkor.github.io
点击进入项目
4.3 进入Settings
菜单：Settings
左侧栏：Environment Variables
4.4 添加环境变量
第一个变量：GITHUB_TOKEN
Name: GITHUB_TOKEN
Value: ghp_xxxxxxxxxxxxxxx (你的Token)
Environments: ✓ Production ✓ Preview ✓ Development
点击：Save
第二个变量：GIST_ID
Name: GIST_ID
Value: abc123def456fg (你的Gist ID)
Environments: ✓ Production ✓ Preview ✓ Development
点击：Save
第三个变量：GITHUB_USERNAME
Name: GITHUB_USERNAME
Value: YultheConkor
Environments: ✓ Production ✓ Preview ✓ Development
点击：Save
4.5 重新部署
菜单：Deployments
点击最新deployment旁的三点菜单
选择：Redeploy
等待部署完成（通常1-2分钟）
检查点：
- 三个环境变量已添加
- 值都正确无误
- 项目已重新部署
- 部署状态显示✅
✏️ 第五步：更新前端配置
5.1 编辑visitor-tracker.js
文件：/assets/js/visitor-tracker.js
找到（约第80行）：
const gistUrl = `https://gist.githubusercontent.com/YultheConkor/PLACEHOLDER_GIST_ID/raw/`;
替换为你的实际URL：
const gistUrl = `https://gist.githubusercontent.com/YultheConkor/abc123def456/raw/`;
检查点：
- 文件路径正确
- URL已更新为实际Gist ID
- 没有多余空格或符号
📤 第六步：推送代码到GitHub
6.1 在本地仓库中提交更改
cd /Users/wanrenwang/warehouse/yultheconkor.github.io
# 查看当前状态
git status
# 添加所有更改
git add .
# 提交更改
git commit -m "Add visitor tracking map with Leaflet and GitHub Gist integration"
6.2 推送到GitHub
git push origin master
6.3 验证推送
打开：https://github.com/YultheConkor/yultheconkor.github.io
检查：最新commit已显示
检查点：
- 代码已本地提交
- 代码已推送到GitHub
- GitHub仓库显示最新commit
🔄 第七步：Vercel自动部署
7.1 等待部署
打开：https://vercel.com/dashboard
找到：yultheconkor.github.io
查看：Deployments 标签
等待：新的deployment完成（通常1-2分钟）
7.2 检查部署状态
新Deployment应该显示：✅ Ready
（如果显示❌ Failed，点击查看错误日志）
7.3 访问网站
打开：https://yultheconkor.github.io
检查：footer中是否显示地图
检查点：
- Vercel已收到推送
- 自动部署已触发
- 部署状态为✅ Ready
- 网站可正常访问
✅ 第八步：验证功能
8.1 检查地图显示
打开网站：https://yultheconkor.github.io
向下滚动到footer
查看：是否显示"👥 Visitors by Location"
是否显示一个地图容器（265x130px）
8.2 检查地图加载
地图应该显示：
✅ 世界地图（OpenStreetMap）
✅ 能够缩放和平移
✅ 显示一个红色虚线圆圈（当前位置）
8.3 检查访问统计
地图下方应该显示：
✅ "Total: X visitors from Y countries"
8.4 浏览器控制台检查
按F12打开开发者工具
查看Console标签
✅ 无红色错误信息
✅ 可能有蓝色的一些info/warn信息（正常）
8.5 检查Gist更新
刷新页面2-3次
打开你的Gist：https://gist.github.com/YultheConkor/abc123def456
检查：是否有新的访问记录被添加
应该显示：新的visitor对象，包含timestamp、country等
8.6 验证IP地理定位
点击地图上的任何标记
弹窗应该显示：城市名、国家名、访问数
检查点：
- 地图正常显示
- 当前位置标记可见
- 访问统计显示正确
- 控制台无红色错误
- Gist有新数据更新
- 标记弹窗信息正确
🐛 故障排查
如果地图不显示
1️⃣ 清除浏览器缓存
Ctrl+Shift+Del（Windows）或 Cmd+Shift+Delete（Mac）
2️⃣ 检查Leaflet库是否加载
F12 → Network标签 → 搜索"leaflet"
应该看到多个请求都是200状态
3️⃣ 检查访问者追踪脚本
F12 → Console标签
查看是否有关于visitor-tracker.js的错误
4️⃣ 检查visitor-tracker.js路径
确认文件在：/assets/js/visitor-tracker.js
如果Gist不更新
1️⃣ 检查环境变量配置
Vercel Dashboard → Settings → Environment Variables
确认三个变量都已设置
2️⃣ 检查Vercel Function日志
Vercel Dashboard → Logs
查看/api/track-visitor的调用记录
3️⃣ 测试Token有效性
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.github.com/user
应该返回用户信息（如果无法运行，忽略此步）
4️⃣ 检查Gist ID
确认值与你的实际Gist ID匹配
如果IP地理定位失败
1️⃣ 检查网络连接
确保可以访问 https://ip-api.com
2️⃣ 检查速率限制
ip-api.com限制45请求/分钟
等待一分钟后重试
3️⃣ 查看控制台错误
F12 → Console标签
查看fetchIPGeolocation相关错误
📞 需要帮助？
查看以下文档：
- 快速部署指南：QUICK_SETUP.md
- 详细配置指南：VISITOR_MAP_SETUP.md
- 系统架构：ARCHITECTURE.md
- 实现总结：IMPLEMENTATION_SUMMARY.md
✨ 完成标志
当你看到以下界面，说明部署成功✅：
┌─────────────────────────────────────────────┐
│ 👥 Visitors by Location │
├─────────────────────────────────────────────┤
│ [显示全球地图的265x130像素框] │
│ [可见红色虚线圆圈表示当前位置] │
│ [可能有其他蓝色-红色圆形标记] │
└─────────────────────────────────────────────┘
Total: X visitors from Y countries
👤Total Visitors Z | 👁️Total Views W
🎉 恭喜！
你已经成功部署了一个功能完整的访问者位置追踪系统！
🚀 下一步可以：
- 分享网站给朋友，积累更多访问记录
- 观察地图中访问者的地理分布
- 考虑添加更多功能（如热力图、排行榜等）
创建时间：2025-10-22 文档版本：v1.0