通过以下步骤快速设置您的个人导航站：

1. 克隆仓库

git clone https://github.com/rbetree/menav.git
cd menav

2. 安装依赖

nvm use
npm install

请确保本机 Node.js 版本为 22.12+；仓库提供 .nvmrc 固定主版本为 22，使用 nvm 时先运行 nvm use。Windows 和 WSL/Linux 环境不要共用 node_modules，请在各自环境中分别安装依赖。

（本仓库的 GitHub Actions/CI 已改为使用 npm ci，以获得更稳定、可复现的依赖安装（基于 package-lock.json）；本地开发可继续使用 npm install，也可直接使用 npm ci。）

3. 初始化并完成配置（见设置配置文件）

npm run init-config

该命令会在 config/user/ 不存在时从 config/_default/ 复制一套完整配置；若 config/user/ 已存在，会直接跳过，避免覆盖您的配置。

4. 导入书签（可选）

   • 将浏览器导出的HTML格式书签文件放入bookmarks目录
   • 运行书签处理命令：

   npm run import-bookmarks

   • 若希望生成结果保持确定性（便于版本管理，减少时间戳导致的无意义 diff）：

   MENAV_BOOKMARKS_DETERMINISTIC=1 npm run import-bookmarks

   • 系统会自动将书签转换为配置文件保存到config/user/pages/bookmarks.yml

• 注意：npm run dev命令不会自动处理书签文件，必须先手动运行上述命令
• npm run dev 默认会刷新 articles/projects 的联网缓存（若你希望离线启动，请使用 npm run dev:offline）
• npm run dev:astro 使用 Astro dev server，适合组件开发；启动前会准备 public/ 资源并监听配置、资源和 runtime 变更

5. 构建

# 启动开发服务器
npm run dev

开发服务器默认从 http://localhost:5173 启动；若默认端口被占用，会自动尝试后续端口。需要固定端口时可设置 PORT=5174 npm run dev 或 MENAV_PORT=5174 npm run dev，显式端口被占用会直接报错。

页面深链接统一使用 /?page=<页面ID>，分类定位使用 /?page=<页面ID>#<分类slug>。未知路径不会自动回跳，静态部署时请分享上述查询参数形式的 URL。

# 离线启动开发服务器（不刷新联网缓存）
npm run dev:offline

# Astro 快速开发模式（组件热更新，仍会校验配置并打包 runtime）
npm run dev:astro

# 生成静态HTML文件（纯离线，不刷新 RSS/GitHub 缓存）
npm run build

构建后的文件位于dist目录。需要刷新 RSS、projects 仓库统计或贡献热力图缓存时，先运行：

npm run sync

npm run generate 与 npm run build 使用同一套离线构建语义；npm run dev 会显式联网刷新缓存，npm run dev:offline 不联网。

6. 提交前检查（推荐）

# 默认快速检查（语法检查 + 单元测试 + 构建 + 最终审计）
npm run check

npm run check 等同于 npm run check:fast，用于日常提交和默认 CI。

# 可选：真实浏览器契约测试（需要 Playwright Chromium）
npm run check:browser

（可选）格式化代码：

npm run format

1. Fork仓库:

   • 点击右上角的 Fork 按钮复制此仓库到您的账号

2. 启用Actions:

   • 进入fork后的仓库
   • 点击顶部的 "Actions" 标签页
   • 点击绿色按钮 "I understand my workflows, go ahead and enable them"

3. 配置Pages:

   • 进入仓库的 Settings -> Pages
   • 在 "Build and deployment" 部分
   • Source: 选择 "GitHub Actions"

创建个人配置文件:

• 重要: 始终创建自己的用户配置文件，不要直接修改默认配置文件
• 完成配置文件（见设置配置文件）
• 提交您的配置文件到仓库

• GitHub Actions会自动检测您的更改
• 构建并部署您的网站
• 部署完成后，您可以在 Settings -> Pages 中找到您的网站地址
  • 站点内容的“时效性数据”（RSS 文章聚合、projects 仓库统计、贡献热力图）会由部署工作流先执行 npm run sync 刷新，再执行离线 npm run build
  • 也支持定时刷新：默认每天 UTC 02:00 触发一次（GitHub Actions cron 使用 UTC；北京时间=UTC+8，可在 .github/workflows/deploy.yml 中调整 schedule.cron）

重要: Sync fork后需要手动触发工作流:

• 当您使用GitHub界面上的"Sync fork"按钮同步本仓库的更新后
• GitHub Actions工作流不会自动运行
• 您需要手动触发构建流程:
  • 进入 Actions 标签页
  • 选择左侧的 "Build and Deploy" 工作流
  • 点击 "Run workflow" 按钮

仓库已内置 docker-compose.yml，并提供 GHCR 预构建镜像；两种方式都建议统一使用 Docker Compose。

说明：容器每次启动都会在容器内执行 npm run build 生成 dist/，然后用 nginx 提供静态文件。

请在仓库根目录执行（需要 config/_default 等文件）。

docker compose pull
docker compose up -d --no-build

docker compose up -d --build

默认访问地址：http://localhost:8080

MENAV_PORT=80 MENAV_ENABLE_SYNC=true MENAV_IMPORT_BOOKMARKS=true docker compose up -d --no-build

• MENAV_PORT：宿主机端口（默认 8080）
• MENAV_ENABLE_SYNC：启动构建时是否联网执行 sync-*（默认 false，更稳定）
• MENAV_IMPORT_BOOKMARKS：启动构建前是否执行 npm run import-bookmarks（默认 false）

• 配置目录挂载在 ./config，个人配置按“完全替换策略”建议：先运行 npm run init-config，再修改 config/user/（见 设置配置文件 与 config/README.md）。
• 如需导入书签：将浏览器导出的书签 HTML 放到 ./bookmarks/，并设置 MENAV_IMPORT_BOOKMARKS=true 后重启容器。
• 修改配置/书签后生效方式（触发重新构建）：

docker compose restart menav

如果您想部署到自己的Web服务器，只需要以下几个步骤：

1. 构建静态网站:

npm run build

npm run build 默认离线。如果需要先刷新 RSS、projects 仓库统计和贡献热力图缓存，请执行 npm run sync && npm run build。

2. 复制构建结果:

   • 所有生成的静态文件都位于 dist 目录中
   • 将 dist 目录中的所有文件复制到您的Web服务器根目录

3. 配置Web服务器:

   • 确保服务器配置为提供静态文件
   • 对于Apache: 在网站根目录中已有正确的 .htaccess 文件
   • 对于Nginx: 添加以下配置到您的server块:

server {
    listen 80;
    server_name your-domain.com;
    root /path/to/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /404.html;
    }
}

4. 更新配置:
   • 如果您想在服务器上更新网站，只需重复上述步骤1-2
   • 或者设置自动部署流程，例如使用GitLab CI/CD或Jenkins

除了GitHub Pages外，您还可以使用其他各种CI/CD服务部署MeNav：

如 Vercel / Netlify / Cloudflare Pages:

• 连接您的GitHub仓库
• 设置构建命令为npm run build
• 设置输出目录为dist

Vercel 部署:

1. 登录 Vercel，点击 Add New... → Project
2. 选择 Import Git Repository，连接并选择你的 MeNav 仓库
3. 构建配置（一般选择 Other 或保持默认自动识别即可）：
   • Build Command: npm run build
   • Output Directory: dist
   • Install Command（可选，但更稳定）：npm ci
4. 点击 Deploy，等待完成后用 Vercel 分配的域名/自定义域名访问

如果您只使用第三方平台部署（不使用 GitHub Pages）：

为避免 GitHub Actions 中的 Pages 配置错误，您可以禁用 GitHub Pages 部署步骤：

1. 进入仓库的 Settings -> Secrets and variables -> Actions
2. 点击 "Variables" 标签页
3. 点击 "New repository variable"
4. 名称填写：ENABLE_GITHUB_PAGES
5. 值填写：false
6. 点击 "Add variable"

设置后，GitHub Actions 仍会自动构建网站（包括书签处理和 npm run sync 等），但会跳过 GitHub Pages 部署步骤，避免报错。第三方平台（如 Vercel/Cloudflare Pages）会自动检测到代码变化并部署。

如果你希望在构建时刷新“时效性数据”（RSS 文章聚合、projects 仓库统计），请将构建命令改为：

npm ci && npm run sync && npm run build

说明：npm run sync 会按 best-effort 顺序执行 projects 仓库统计、贡献热力图和 RSS 文章聚合，并写入 dev/ 缓存（仓库默认 gitignore）；同步失败会记录告警但不阻断后续 build。

备注：dev/ 只用于构建过程的中间缓存，默认不会被提交到仓库；部署时也只会上传 dist/，不会包含 dev/。

书签转换依赖 GitHub Actions 如果需要使用书签自动推送功能，必须先在 GitHub 仓库中启用 GitHub Actions

部署流程：

1. 上传书签 → 2. GitHub Actions 处理 → 3. 使用处理完成的代码在 GitHub Pages 自动部署
                           ↓
          4. 其他 CI/CD 托管平台检测到变化 → 5. 使用处理完成的代码自动部署

无论选择哪种部署方式，请确保创建并使用您自己的配置文件，而不是直接修改默认配置。