Shigure

Shigure 是一个基于 React + Tailwind CSS 的网页时钟与网易云音乐播放器。

• 在线地址：https://shigure.xnlemon.top
• 音乐 API：NeteaseCloudMusicApi Enhanced
• 默认时区：北京时间（Asia/Shanghai）

功能

• 数字时钟：显示 HH:MM:SS、YYYY/MM/DD 和星期
• 固定显示北京时间，不受访问者浏览器本地时区影响
• 中英文界面切换（zh-CN / en-US）
• 内置多张背景图
• 上传并更换自定义背景
• 每个浏览器配置独立保存登录态、背景偏好和上传背景
• 定时器：预设时长、自定义分钟数、暂停、重置
• 网易云音乐搜索
• 网易云账号登录：手机号 + 密码、短信验证码、二维码登录
• 网易云歌单：加载用户歌单、歌单 ID 或链接、歌单内搜索歌曲
• 播放、暂停、上一首、下一首、音量和播放进度控制
• 响应式布局，适配桌面端和移动端

技术栈

• React 18
• Vite 6
• Tailwind CSS 3
• Lucide React
• NeteaseCloudMusicApi Enhanced

项目结构

.
├── src/
│   ├── components/          # 时钟、播放器、登录、背景、定时器等组件
│   ├── i18n/                # 中英文翻译和语言切换
│   ├── lib/                 # 时间、歌单 ID、音频时长等格式化工具
│   ├── App.jsx              # 页面状态和主要交互
│   ├── browserStorage.js    # 浏览器隔离存储和 IndexedDB 背景资源
│   ├── neteaseApi.js        # 网易云 API 请求封装
│   ├── constants.js         # 预设背景配置
│   └── index.css            # Tailwind 基础样式和组件样式
├── index.html
├── package.json
├── tailwind.config.js
├── postcss.config.js
└── .env.example

本地开发

环境要求

• Node.js 18 或更高版本
• npm

安装依赖

npm install
Copy-Item .env.example .env

编辑 .env：

VITE_NCM_API_URL=http://localhost:3000

VITE_NCM_API_URL 是 Vite 构建时注入的变量。修改后需要重新启动开发服务器或重新构建。

启动开发服务器

npm run dev

默认地址通常是 http://localhost:5173。

构建和预览

npm run build
npm run preview

构建产物位于 dist/。dist/、node_modules/ 和 .env 已加入 .gitignore。

网易云 API

Shigure 需要一个可访问的 NeteaseCloudMusicApi Enhanced 服务。前端使用的主要接口包括：

用途	接口
登录状态	/login/status
密码登录	/login/cellphone
短信验证码	/captcha/sent/v1
二维码登录	/login/qr/key、/login/qr/create、/login/qr/check
音乐搜索	/cloudsearch
播放地址	/song/url/v1
用户歌单	/user/playlist
歌单详情	/playlist/detail
歌单歌曲	/playlist/track/all

API 服务需要：

1. 允许 Shigure 前端域名的 CORS 请求。
2. 通过 HTTPS 对外提供服务。
3. 在生产环境中保留网易云登录接口所需的 Cookie。
4. 不要把 API 容器端口直接暴露到公网，建议只监听服务器本机并由 Nginx 反代。

生产环境示例：

VITE_NCM_API_URL=https://xnlemon.top/shigure-api

部署

服务器 API 反代

当前 API 容器仅监听服务器本机的 3100 端口，Nginx 对外提供 /shigure-api/ 路径。二维码登录会返回较大的 Cookie 响应头，因此反代位置需要配置足够的缓冲区：

location /shigure-api/ {
    proxy_pass http://127.0.0.1:3100/;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    proxy_buffer_size 128k;
    proxy_buffers 4 256k;
    proxy_busy_buffers_size 256k;
    proxy_read_timeout 30s;
}

修改 Nginx 配置后先检查，再 reload：

sudo nginx -t
sudo systemctl reload nginx

不需要开放 3100 公网端口；防火墙只需要允许已有的 HTTPS 入口。

浏览器数据和隐私

Shigure 不需要自己的用户数据库。登录态和界面偏好保存在用户浏览器中：

• localStorage：保存浏览器标识、登录态、语言和背景偏好
• sessionStorage：在 localStorage 不可用时作为回退
• IndexedDB：保存上传的背景图片文件
• 不同浏览器配置使用不同的存储命名空间

清除站点数据会同时清除该浏览器配置的登录态和上传背景。登录 Cookie 属于敏感信息，请始终使用 HTTPS，并避免在公共电脑上保存登录状态。

常见问题

页面提示无法连接音乐服务

检查以下内容：

1. VITE_NCM_API_URL 是否指向可访问的 API 地址。
2. API 服务是否启动。
3. API 是否允许 https://shigure.xnlemon.top 的 CORS 请求。
4. 浏览器是否仍使用旧资源，必要时执行强制刷新。
5. 直接访问 API 的登录状态接口：

curl -i https://xnlemon.top/shigure-api/login/status

二维码轮询返回 502

如果 Nginx 日志出现以下错误：

upstream sent too big header while reading response header from upstream

请确认 /shigure-api/ 位置包含 proxy_buffer_size、proxy_buffers 和 proxy_busy_buffers_size 配置。修复后重新生成二维码，旧二维码不应继续使用。

某首歌曲没有声音

网易云可能因为版权、地区、会员权限或歌曲状态返回空播放地址。这通常是单曲资源不可用，不代表 API 服务整体异常，可以尝试其他歌曲。

上传背景无法保存

上传背景使用 IndexedDB 保存。若浏览器禁用了 IndexedDB、处于严格隐私模式，或图片过大，页面会回退到当前会话并提示保存失败。可以压缩图片后重试。

开发约定

• 新增界面文案时，同时更新 src/i18n/locales/en-US.js 和 src/i18n/locales/zh-CN.js。
• 不要把用户可见文本直接写死在组件中。
• API 地址通过 VITE_NCM_API_URL 配置，不要写入组件标题或界面文案。
• 提交代码前执行 npm run build。
• 不要提交 .env、服务器密码或网易云登录 Cookie。

相关项目

• NeteaseCloudMusicApi Enhanced：https://github.com/neteasecloudmusicapienhanced/api-enhanced