---
name: github-showcase-netlify
description: 用中文帮助用户把 GitHub 项目数据整理成静态展示网站，并发布到 Netlify。适用于用户想从 GitHub、HelloGitHub 或本地 JSON 获取项目数据，生成或更新 Vite/React 静态网站，配置 netlify.toml，登录/链接 Netlify，执行预览或生产发布，并把“获取项目数据到发布网站”的流程做成可复用步骤时。
---

# GitHub 项目展示站发布

## 核心目标

用中文引导用户完成一条完整链路：

1. 明确要展示哪些 GitHub 项目。
2. 使用项目自带脚本或公开 API 刷新项目数据。
3. 更新静态网站内容。
4. 本地构建并检查产物。
5. 配置并登录 Netlify。
6. 发布网站，返回线上地址并做访问验证。

这个 skill 要服务学生和新手。回答时保持中文、步骤清楚、少说术语；遇到必须登录、授权、创建账号的步骤，要明确告诉用户需要他们本人操作。

## 使用前提

先检查当前项目是否具备这些基础文件：

```bash
package.json
src/
public/
```

常见 Vite/React 项目通常使用：

```bash
npm install
npm run build
```

如果项目有数据同步脚本，优先使用项目自己的脚本，例如：

```bash
npm run sync:data
```

不要临时编造 GitHub 项目数据。无法联网或 API 失败时，要报告真实错误，并让用户稍后重试或提供数据文件。

## 推荐流程

### 1. 了解用户要展示的项目来源

先判断数据来自哪里：

- GitHub 仓库列表：用户给出若干 GitHub URL。
- HelloGitHub：项目里已有同步脚本或数据文件。
- 本地 JSON/CSV：用户已经整理好项目数据。
- 手工输入：用户临时给出项目名称、链接、简介。

如果信息不够，优先问最少的问题：

```text
你想展示哪些项目？可以发 GitHub 链接、一个项目列表，或者告诉我使用现有的数据同步脚本。
```

### 2. 刷新或生成项目数据

如果项目有 `sync:data`：

```bash
npm run sync:data
```

然后检查常见数据文件：

```bash
src/data/*.json
public/data/*.json
```

如果没有同步脚本，但用户给了 GitHub URL，可以用 GitHub API 或网页信息整理成项目需要的 JSON 结构。写入前先查看现有数据结构，保持字段一致。

### 3. 检查 Netlify 配置

如果缺少 `netlify.toml`，为 Vite 静态站添加最小配置：

```toml
[build]
  command = "npm run build"
  publish = "dist"
```

如果项目不是 Vite，要根据实际框架调整：

| 项目类型 | 常见构建命令 | 常见发布目录 |
| --- | --- | --- |
| Vite / React | `npm run build` | `dist` |
| Create React App | `npm run build` | `build` |
| Astro | `npm run build` | `dist` |
| 纯 HTML | 无需构建 | 当前目录或 `public` |

### 4. 本地构建

发布前必须先构建：

```bash
npm install
npm run build
```

如果构建失败，先修复失败原因，不要继续发布。

### 5. 登录并发布到 Netlify

检查登录状态：

```bash
npx netlify status
```

如果未登录，让用户执行：

```bash
npx netlify login
```

用户完成浏览器授权后再继续。

如果项目已经链接 Netlify：

```bash
npx netlify deploy --prod --dir dist --no-build
```

如果项目还没有链接，可以指定站点名创建并发布：

```bash
npx netlify deploy --prod --site-name <站点名> --dir dist --no-build
```

### 6. 验证并总结

发布完成后，提取并告诉用户：

- 生产地址，也就是用户真正要分享的网址。
- 本次部署地址。
- Netlify 后台日志地址。

再做一次访问检查：

```bash
curl -I <生产地址>
```

首页返回 `200` 才算基本发布成功。

## 一键脚本

本 skill 附带脚本：

```bash
scripts/deploy-showcase.sh
```

在项目根目录中运行它。不要在文档里写死某个人电脑上的绝对路径；如果需要调用脚本，应根据 skill 当前所在目录来引用，或者先进入 skill 目录再执行。

常用参数通过环境变量传入：

```bash
NETLIFY_SITE_NAME=my-github-showcase \
PUBLISH_DIR=dist \
BUILD_COMMAND="npm run build" \
scripts/deploy-showcase.sh /path/to/project
```

含义：

- `NETLIFY_SITE_NAME`：Netlify 站点名。不填时脚本会根据 `package.json` 的 `name` 自动生成。
- `PUBLISH_DIR`：构建产物目录，默认 `dist`。
- `BUILD_COMMAND`：构建命令，默认 `npm run build`。
- 最后的路径参数：项目根目录。不填时默认当前目录。

## 给学生使用时的注意点

- 要求学生先安装 Node.js，并能运行 `npm`。
- 要求学生有 Netlify 账号。
- 第一次发布时，Netlify 登录必须由学生本人在浏览器中授权。
- 不要把老师电脑上的 `.netlify/state.json`、账号 token 或个人路径发给学生。
- 可以分发整个 skill 文件夹，但不要把某个项目的 `node_modules`、`dist` 或个人截图一起当成 skill 内容。

## 输出风格

使用这个 skill 时，默认用中文回答。每次完成发布后，用简短清单说明：

- 做了哪些数据更新。
- 构建是否成功。
- 发布到哪个 Netlify 站点。
- 线上地址是什么。
- 是否已经用 HTTP 状态码检查过。