网站维护说明

环境与本地运行

项目要求 Node.js 22.12.0 或更高版本，推荐使用 Node.js 24 LTS 和随 Node.js 安装的 npm。首次运行先安装锁定依赖：

npm ci --no-audit --no-fund
npm run dev

从仓库首次安装或恢复锁定依赖时统一使用 npm ci。只有在主动添加、删除或升级依赖时才使用 npm install，并检查 package-lock.json 的变化。

@emnapi/core 和 @emnapi/runtime 是用于规避 npm 跨平台锁文件可选依赖缺失问题的兼容项。即使源码没有直接导入，也不要随意删除。

浏览器打开 http://localhost:4321/。开始修改前先执行 git status，避免覆盖其他维护者尚未提交的内容。

npm run dev

启动本地开发服务器并自动刷新

npm run check

检查 Astro、TypeScript 和内容字段

npm run build

构建生产版本到 dist/

npm run preview

本地预览已经构建的生产版本

npm run new:article -- article-slug "文章标题"

创建一篇文章草稿

项目结构与内容位置

普通内容更新主要集中在以下文件，不需要修改构建产物：

src/content/articles/

Markdown 文章正文与 Frontmatter

src/data/members.ts

成员届别、昵称、方向和公开联系方式

src/data/honors.ts

竞赛荣誉、排名、成员和公开链接

src/data/recruitment.json

微信公众号名称和纳新 QQ 群号

src/data/site.json

团队名称、简介、地点、GitHub 和公开邮箱

src/pages/

页面结构和页面专属样式

src/components/

多个页面共用的组件

src/styles/

全局样式、主题变量和首页样式

public/images/

文章、团队和页面使用的图片

public/downloads/

需要公开下载的 PDF 等文件

不要直接修改 dist/。该目录由构建命令重新生成，手工改动会在下次构建时丢失。

新建与更新文章

使用脚本创建文章草稿：

npm run new:article -- article-slug "文章标题"

article-slug 只能包含小写字母、数字和连字符，并会成为文章 URL 的一部分。已有文章不要随意改名，否则原链接会失效。

文章的 Frontmatter 示例：

---
title: "文章标题"
description: "用于文章列表和搜索结果的一到两句话摘要。"
publishedAt: 2026-08-01
category: "技术文章"
tags: ["Web", "复盘"]
author: "作者昵称"
draft: true
cover: "/images/articles/example/cover.webp"
---

Frontmatter 的常用字段如下：

title

文章标题

description

列表页和搜索使用的摘要，至少十个字

publishedAt

发布日期，格式为 YYYY-MM-DD

updatedAt

可选；文章有重要更新时填写

category

团队动态、技术文章、赛事复盘或纳新公告

tags

标签数组，列表页最多显示三个

author

作者昵称或“智邮普创工作室”

draft

true 时不进入文章列表、RSS 和 Sitemap

cover

可选；public 目录下资源对应的站内路径

完成正文并检查后，将 draft 改为 false。文章字数会在构建时自动计算；封面不是必填项，没有合适图片时保留纯文字卡片即可。

文章封面放入 public/images/articles/，并在 cover 中填写以 /images/ 开头的站内路径。

更新成员与荣誉

成员

编辑 src/data/members.ts，在对应届别的 entries 数组中追加成员：

{
  nickname: '昵称',
  sitenick: 'web',
  title: '页面显示名称',
  directions: ['Web 安全'],
  avatar: '/images/members/example.webp',
  qq: '公开 QQ 号',
  github: 'GitHub 用户名',
  blog: 'https://example.com/',
}

avatar、qq、github 和 blog 都可以省略。新增届别时复制完整年份分组。

荣誉

编辑 src/data/honors.ts，在对应年份的 entries 数组中追加记录：

{
  month: 10,
  competition: '比赛全称',
  award: '全国二等奖',
  rank: '全国第 12 名',
  track: 'CTF',
  members: ['成员昵称'],
  url: 'https://example.com/writeup',
}

rank、members 和 url 可以省略。页面会按年份和月份倒序显示，发布前必须核实记录。

联系方式与站点信息

• src/data/recruitment.json：维护公众号名称和纳新 QQ 群号。
• src/data/site.json：维护团队名称、简介、地点、GitHub 和可选邮箱。
• src/pages/join.astro：维护安全组流程、准备建议、开发组说明和常见问题。

[
  {
    "id": "main",
    "qqGroup": "1057111048",
    "wechatAccount": "智邮普创实验室"
  }
]

加入页面不维护报名状态、截止日期、倒计时或二维码。开发组资料没有确认前，不要自行补写技术栈和选拔流程。

图片、PDF 与静态资源

• public/images/articles/example/cover.webp 发布后对应 /images/articles/example/cover.webp。
• public/downloads/example.pdf 发布后对应 /downloads/example.pdf。
• 历年面试题原 PDF 位于 public/downloads/interviews/，文件名与加入页面的下载链接对应。

图片应先压缩，照片优先使用 WebP。不要提交无关原图、临时截图或包含未授权个人信息的文件。

检查、构建与发布

每次提交前至少运行：

npm run check
npm run build

涉及页面结构或样式时，还要检查桌面端、移动端、浅色与深色主题、键盘焦点、页面跳转和横向溢出。

确认无误后查看改动范围并提交：

git status
git diff
git add <本次修改的文件>
git commit -m "说明本次修改"
git push

部署

当前正式域名为 https://zypc.xupt.edu.cn，服务器项目目录为 /www/wwwroot/zypc，宝塔网站运行目录为 /dist。服务器拉取 main 后执行：

cd /www/wwwroot/zypc
npm ci --no-audit --no-fund
npm run check
npm run build

Nginx 只提供 /www/wwwroot/zypc/dist，不要暴露仓库根目录、.git 或源码。astro.config.mjs 已配置正式域名；只有网站迁移到其他域名时才需要修改 site。

安全与交接

• 不要把密码、私钥、Cookie、Webhook 密钥或服务器凭据写进仓库。
• 不要随意删除或重命名已有文章和公开资源，避免旧链接失效。
• 公开成员资料、文章署名和照片前确认授权，必要时使用昵称和打码图片。
• 通过平台成员权限交接仓库、域名和部署服务，不在聊天记录中发送私钥。
• 说明未发布草稿、待确认资料、部署方式和当前未提交修改。
• 交接前让下一位维护者独立完成一次本地启动、内容修改、检查和构建。