魔法上网指南 (mofa.gg)

中文优先的科学上网 / 机场 / VPS / Clash / AI 工具访问指南站。

不仅仅是教程聚合 —— 一个按场景组织、SEO 友好、转化路径清晰、可信度强的长期维护站点。

🌐 正式域名（未启用）： https://mofa.gg — 项目完工、DNS 解析到位后才切换 🔧 当前对外域名： https://mofa-guide.pages.dev（预览阶段，所有 canonical / og / sitemap / RSS 均指向此域名）

上线开关： .vitepress/constants.ts 里的 LIVE 当前为 false。预览阶段对外 URL 全部用 mofa-guide.pages.dev、robots.txt 禁止收录、不生成 CNAME。项目完工、mofa.gg 解析到位后，把 LIVE 改为 true 即可一键切回正式域名（同时恢复收录与 CNAME），无需改动其它文件。

技术栈

• VitePress v1.6.4 — 静态站点生成器
• Vue 3 — 自定义主题组件
• TypeScript — 脚本（通过 tsx 运行，无编译步骤）
• Cloudflare Pages — 部署平台
• ESM ("type": "module") — Node 20.11+

本地开发

npm install            # 安装依赖（首次）
npm run dev            # 生成搜索索引 + 启动 VitePress 开发服务器（热重载）
npm run build          # 生产构建 → .vitepress/dist/
npm run preview        # 本地预览生产构建

维护命令

npm run check-links       # 校验所有内部相对链接
npm run check-freshness   # 报告 90 天以上未更新的页面
npm run update-dates      # 批量刷新「最近更新」日期
npm run sitemap           # 生成 sitemap.xml（需先构建）
npm run rss               # 生成 RSS feed（需先构建）
npm run build-search-index # 生成全文搜索索引 public/search-index.json
npm run full-build        # update-dates → build → sitemap → rss（部署前完整构建）
npm run maintain          # check-links + check-freshness + update-dates（日常维护）

项目结构

mofa.gg/
├── index.md                  # 首页（由 Layout.vue 按路径识别）
├── about.md / changelog.md   # 根级公开页
├── disclaimer.md             # 免责声明
├── affiliate-disclosure.md   # 推广与返佣披露
├── privacy.md                # 隐私政策
├── guide/                    # 指南与教程（how-to / 参考）
│   ├── compare.md            # 方案全面对比
│   ├── quickstart.md         # 零基础订阅教程
│   ├── choose-plan.md        # 1 分钟选方案
│   ├── providers.md          # 机场选购避坑
│   ├── methodology.md        # 推荐与评估方法
│   ├── platforms.md          # 各平台客户端配置
│   ├── clash-verge-rev-windows.md  # Clash Verge Rev Windows 教程
│   ├── shadowrocket-ios.md   # Shadowrocket iOS 教程
│   ├── vps.md                # 自建 VPS 指南
│   ├── router.md             # 软路由 / 全屋代理
│   ├── route.md              # 线路科普
│   ├── protocols.md          # 协议科普
│   ├── speedtest.md          # 测速指南
│   ├── troubleshooting.md    # 排障指南
│   ├── chatgpt-403.md        # ChatGPT 403 怎么办
│   ├── claude-unavailable.md # Claude unavailable 怎么办
│   ├── faq.md                # 常见问答
│   ├── security.md           # 安全与隐私
│   ├── compliance.md         # 机场合规与法律
│   ├── isp.md                # 运营商检测与应对
│   ├── glossary.md           # 名词解释
│   └── sites.md              # 网站导航
├── scenarios/                # 场景入口（任务导向）
│   ├── index.md              # 场景中心
│   ├── ai.md                 # 用 ChatGPT / Claude
│   ├── streaming.md          # 看 Netflix / YouTube
│   ├── gaming.md             # 打游戏低延迟
│   ├── vps-selfhost.md       # 自建节点
│   ├── beginner.md           # 零基础入门
│   └── choose-provider.md    # 选机场不踩坑
├── public/                   # 静态资源（原样复制到 dist）
├── scripts/                  # 维护脚本（TypeScript，tsx 运行）
├── .vitepress/
│   ├── config.ts             # VitePress 配置（导航/侧边栏/SEO/构建钩子）
│   ├── constants.ts          # 共享常量（SITE_URL / SITE_NAME / 字体栈）
│   └── theme/
│       ├── links.ts          # 导航单一数据源（config.ts 和组件共用）
│       ├── Layout.vue        # 自定义根布局
│       ├── assets/main.css   # 设计 token + 全局样式
│       └── components/       # 19 个 Vue 组件
└── .github/workflows/        # CI（deploy.yml / link-check.yml）

内容写作规范

Frontmatter

每个 .md 页必须包含：

---
title: "页面标题"
description: "SEO 描述（用于 OG / canonical / 搜索摘要）"
date: 2026-06-26
updated: 2026-06-26
category: "入门 | 教程 | 参考 | 排障 | 场景 | 合规 | 安全"
tags:
  - "标签1"
  - "标签2"
difficulty: "beginner | intermediate | advanced"
last_verified: 2026-06-26
---

页面正文

• 最近更新：YYYY-MM-DD 行（有实质改动时更新）
• ## 推荐阅读 小节（链接到相关页面）
• 内部链接用不带 .md 的相对路径：[排障指南](./guide/troubleshooting)
• 不要用 .html 后缀

可用组件

在 .md 文件中可直接使用 5 个全局 Vue 组件：

• <Tip> — 提示框（type: tip/info/warning/danger/success）
• <CompareTable> — 响应式对比表
• <FaqItem> — 可折叠 FAQ
• <Steps> — 步骤列表
• <UpdateBadge> — 日期徽章

新增文章流程

1. 在 guide/ 或 scenarios/ 下创建 .md 文件
2. 按规范写好 frontmatter 和正文
3. 在 .vitepress/theme/links.ts 的 guideGroups 中添加条目
   • config.ts 的 nav / sidebar 会自动同步（它从 links.ts 导入）
4. 将文件名加入 .vitepress/config.ts 的 srcExclude（如果该页面不便公开）
5. 运行 npm run check-links 确保链接有效
6. 运行 npm run dev 本地预览

部署

部署由推送到 main 分支触发（GitHub Actions）：

1. npm ci → link check → npm run build → sitemap → RSS
2. 通过 cloudflare/pages-action 上传 .vitepress/dist/ 到 Cloudflare Pages项目：mofa-guide

重要：npm run deploy 仅是本地 dry-run，不会上传到 Cloudflare。

所需密钥

GitHub Actions secrets：

• CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID

域名与上线开关（LIVE）

• 对外 URL 由 .vitepress/constants.ts 的 LIVE 开关控制，是全站唯一数据源（canonical / og:url / sitemap / robots / RSS / CNAME 全部派生自它，不要在别处硬编码）：
  • LIVE = false（当前预览阶段）：SITE_URL 用 https://mofa-guide.pages.dev；robots.txt 输出 Disallow: / 禁止收录；不生成 CNAME（避免 Cloudflare 绑定尚未解析的 mofa.gg）。
  • LIVE = true（项目完工、mofa.gg DNS 解析到位后切换）：SITE_URL 切回 https://mofa.gg；robots.txt 开放收录；生成 CNAME。
• 上线步骤： 把 LIVE 改为 true → 重新构建部署 → 在 Cloudflare Pages 绑定自定义域 mofa.gg，并把 *.pages.dev 301 重定向到 mofa.gg，避免预览域名被索引造成重复内容。

GitHub 仓库设置建议（手动，在仓库 Settings 中配置）

代码不会改动 GitHub 仓库元信息，请手动在 GitHub 仓库页右上「About / ⚙️」中设置，以提升可信度与可发现性：

• Description： 中文优先的科学上网 / 机场 / VPS / Clash / AI 工具访问指南站 —— 按场景选型、SEO 友好、长期维护。
• Website： 预览阶段填 https://mofa-guide.pages.dev，正式上线后改为 https://mofa.gg
• Topics： clash、mihomo、sing-box、vpn、vps、proxy、shadowrocket、chatgpt、vitepress、china、gfw、science-online

合规与免责

• 本站为技术科普与信息整理，不鼓励任何违法用途
• 推荐信息可能过期，请以第三方页面最新信息为准
• 不建议直接年付或大额充值，建议先月付小额试用
• 部分链接可能包含 affiliate / 返佣，不影响你的购买价格
• 用户应遵守所在地法律法规
• 详见：免责声明 | 推广披露 | 合规与法律

License

ISC