nuxt-portfolio-studio — Nuxt Portfolio Template

SHA-256: 6dac44d7d3df913e28f0c03668a5f8dbae7cc49dd89bae97919ef6b9b2f2acd0

2026-10-01T13:57:08.648Z

# Nuxt Portfolio Studio

> A local-first portfolio template with a visual content editor.

一个面向开发者的开源个人主页模板，定位是“数字名片 + 作品集入口”。项目使用 Nuxt 3 静态生成，并提供仅在本地开发环境可用的可视化内容后台。

仓库默认包含 Lunan 的公开主页作为演示；Fork 后可通过本地后台替换为自己的资料，无需修改页面组件。

![Nuxt Portfolio Studio 默认演示站截图](./docs/screenshots/home-desktop.png)

## 功能亮点

- 首页包含个人介绍、代表项目、近期文章、技能与联系方式
- 响应式布局、移动端导航及浅色 / 深色主题
- 键盘焦点、跳过导航、减少动画等可访问性支持
- 页面内容集中保存在 `data/home.json`
- 本地内容后台可维护资料、项目、文章与区块文案
- 生产环境为纯静态站点，不暴露后台页面和写入接口
- 内置 GitHub Pages 自动部署，也适合 Cloudflare Pages 等静态托管服务

## 技术栈

- Nuxt 3
- Vue 3
- TypeScript
- Tailwind CSS
- Static Site Generation（SSG）

## 快速开始

需要 Node.js 20 或更高版本，以及 pnpm 9。

```bash
pnpm install
pnpm dev
```

开发服务默认运行在 `http://localhost:3000`。

## 本地内容后台

如果只需要更新主页内容，推荐启动本地后台：

```bash
pnpm admin
```

然后访问 `http://127.0.0.1:3000/admin`。

![Nuxt Portfolio Studio 本地内容后台截图](./docs/screenshots/admin-desktop.png)

后台会把修改保存到 `data/home.json`。它只在开发模式下注册，并限制为本机访问；执行静态生成后不会产生 `/admin` 页面，也不会包含内容写入接口。

更完整的字段说明和操作流程见 [个人主页内容更新指南](./CONTENT_UPDATE_GUIDE.md)。

## 内容结构

```text
data/
├─ home.json     # 后台维护的全部主页内容
├─ site.ts       # 读取品牌、链接与 SEO
├─ profile.ts    # 读取首页介绍、技能与个人标签
├─ projects.ts   # 读取项目数据
├─ articles.ts   # 读取文章数据并拼接博客域名
└─ links.ts      # 根据站点配置生成社交入口
```

日常更新只需要使用本地后台，或直接编辑 `data/home.json`，无需修改页面组件。

## Fork 后必须替换

本仓库保留了作者的公开资料与个人视觉资产。将它用于自己的主页前，请至少检查以下内容：

- `data/home.json` 中的姓名、介绍、邮箱、GitHub、博客、项目和文章
- `public/profile-portrait-720.jpg` 与 `public/profile-portrait-1080.jpg`
- `public/avatar-square.png`
- `public/favicon.svg` 与 `public/og-cover.svg`
- `public/site.webmanifest` 中的名称和图标声明
- README 中的项目名称、截图和说明

不要直接沿用原作者的头像、品牌图形或个人内容发布自己的站点。相关边界见 [素材许可说明](./ASSETS_LICENSE.md)。

## 检查与构建

```bash
# 类型检查并生成静态站点
pnpm check

# 单独执行安全审计
pnpm audit:security

# 本地复现 GitHub Pages 构建
pnpm build:pages
```

静态产物生成在 `.output/public`，不会提交到 Git：

```bash
pnpm preview
```

## GitHub Pages 自动部署

仓库内置 `.github/workflows/deploy-pages.yml`。推送到 `main` 后，会自动检查、构建并发布 `.output/public`。

首次使用时，在 GitHub 仓库打开：

```text
Settings → Pages → Build and deployment → Source → GitHub Actions
```

工作流会自动处理两种地址：

- 普通仓库：`https://<用户名>.github.io/<仓库名>/`
- 用户主页仓库：`https://<用户名>.github.io/`

如果配置了自定义域名，请在 `Settings → Secrets and variables → Actions → Variables` 新增：

```text
NUXT_APP_BASE_URL=/
```

保存后重新运行部署工作流即可。部署完成后，地址会显示在仓库的 **Deployments** 和 **Settings → Pages** 中。

## Cloudflare Pages 部署

在 Cloudflare Pages 连接仓库后，使用以下配置：

| 配置项 | 值 |
| --- | --- |
| Framework preset | Nuxt.js |
| Build command | `pnpm generate` |
| Build output directory | `.output/public` |
| Node.js version | `20` 或更高 |

如果平台没有自动识别 pnpm，可设置：

```text
PNPM_VERSION=9.14.4
```

## 目录结构

```text
nuxt-portfolio-studio/
├─ .github/workflows/deploy-pages.yml
├─ .github/workflows/quality.yml
├─ assets/css/main.css
├─ components/
│  ├─ common/
│  ├─ home/
│  └─ layout/
├─ data/
├─ docs/screenshots/
├─ layouts/
├─ pages/
│  ├─ index.vue
│  └─ admin.vue        # 仅开发模式注册
├─ public/
├─ server/api/admin/   # 仅本机开发模式可用
├─ types/
├─ app.vue
├─ nuxt.config.ts
└─ tailwind.config.ts
```

## 安全与贡献

- 安全问题请按 [SECURITY.md](./SECURITY.md) 提交，避免在公开 Issue 中披露细节。
- 参与开发前请阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)。
- GitHub Actions 会在推送和拉取请求中执行依赖安装、类型检查、静态生成与高危依赖审计。

## 许可

项目代码采用 [MIT License](./LICENSE)。头像、品牌图形、页面截图与 `data/home.json` 中的个人内容不包含在 MIT 授权范围内，详见 [ASSETS_LICENSE.md](./ASSETS_LICENSE.md)。