使用cf worker部署Github镜像站

前言

玩自托管、跑脚本的朋友，几乎都被 GitHub 的"网络问题"折磨过。尤其在国内直连环境下，经常遇到这种情况：

用脚本或配置时，需要从 GitHub 下载一些文件，结果下不动、超时、报错；
明明项目是好的，可就是因为某些 release、源码、规则的 URL 连不上，整个流程卡死。

根因大多是 GitHub 的部分域名/CDN 在国内访问不稳定。要解决，最常用的思路就是搭一个 GitHub 镜像/代理站——你请求镜像站，它帮你转发到 GitHub 并回传结果，这样绕开了直连的不稳定。

常见的做法是自建 gh-proxy。而这个项目最爽的一点是：可以部署在 Cloudflare Workers 上，不用自己买服务器，免费额度对个人用完全够。本文就记录怎么用 Cloudflare Worker 快速搭一个 GitHub 镜像站。

项目地址：https://github.com/hunshcn/gh-proxy

它解决什么问题

先搞清楚这个镜像站能加速哪些内容：

Release / 压缩包下载：GitHub 上项目的发布包（releases、archive）。
raw / blob 文件：GitHub 仓库里的单个源码文件（raw 链接）。
git 相关：部分 git 协议相关的加速。
脚本运行时下载：很多安装脚本在执行时会从 GitHub 拉依赖文件，通过镜像站能稳定拿到。

简单说，它就是给"从 GitHub 下载东西"这件事加了一层国内可用的代理。

CF Worker 版本部署

整体流程：建 Worker → 粘贴项目代码 → 部署 → 绑定域名。

第 1 步：登录 Cloudflare Workers

打开 Workers 控制台：https://workers.cloudflare.com，用你的 Cloudflare 账号登录。

第 2 步：创建一个 Worker

在 Workers & Pages 页面，点 创建应用程序 / Create application，选 Worker，创建一个新的 Worker（名字随意，比如 gh-proxy）。

第 3 步：进入代码编辑

创建后进入这个 Worker 的详情页，点 编辑代码 / Edit code，打开在线编辑器。

第 4 步：把默认代码替换成项目代码

把 Worker 里默认的模板代码，整体替换成 gh-proxy 的代码。源码在：

index.js

完整代码如下（直接复制替换即可）：

纯文本

'use strict'

/**
 * static files (404.html, sw.js, conf.js)
 */
const ASSET_URL = 'https://hunshcn.github.io/gh-proxy/'
// 前缀，如果自定义路由为example.com/gh/*，将PREFIX改为 '/gh/'，注意，少一个杠都会错！
const PREFIX = '/'
// 分支文件使用jsDelivr镜像的开关，0为关闭，默认关闭
const Config = {
    jsdelivr: 0
}

const whiteList = [] // 白名单，路径里面有包含字符的才会通过，e.g. ['/username/']

/** @type {ResponseInit} */
const PREFLIGHT_INIT = {
    status: 204,
    headers: new Headers({
        'access-control-allow-origin': '*',
        'access-control-allow-methods': 'GET,POST,PUT,PATCH,TRACE,DELETE,HEAD,OPTIONS',
        'access-control-max-age': '1728000',
    }),
}

const exp1 = /^(?:https?:\/\/)?github\.com\/.+?\/.+?\/(?:releases|archive)\/.*$/i
const exp2 = /^(?:https?:\/\/)?github\.com\/.+?\/.+?\/(?:blob|raw)\/.*$/i
const exp3 = /^(?:https?:\/\/)?github\.com\/.+?\/.+?\/(?:info|git-).*$/i
const exp4 = /^(?:https?:\/\/)?raw\.(?:githubusercontent|github)\.com\/.+?\/.+?\/.+?\/.+$/i
const exp5 = /^(?:https?:\/\/)?gist\.(?:githubusercontent|github)\.com\/.+?\/.+?\/.+$/i
const exp6 = /^(?:https?:\/\/)?github\.com\/.+?\/.+?\/tags.*$/i

/**
 * @param {any} body
 * @param {number} status
 * @param {Object<string, string>} headers
 */
function makeRes(body, status = 200, headers = {}) {
    headers['access-control-allow-origin'] = '*'
    return new Response(body, {status, headers})
}

/**
 * @param {string} urlStr
 */
function newUrl(urlStr) {
    try {
        return new URL(urlStr)
    } catch (err) {
        return null
    }
}

addEventListener('fetch', e => {
    const ret = fetchHandler(e)
        .catch(err => makeRes('cfworker error:\n' + err.stack, 502))
    e.respondWith(ret)
})

function checkUrl(u) {
    for (let i of [exp1, exp2, exp3, exp4, exp5, exp6]) {
        if (u.search(i) === 0) {
            return true
        }
    }
    return false
}

/**
 * @param {FetchEvent} e
 */
async function fetchHandler(e) {
    const req = e.request
    const urlStr = req.url
    const urlObj = new URL(urlStr)
    let path = urlObj.searchParams.get('q')
    if (path) {
        return Response.redirect('https://' + urlObj.host + PREFIX + path, 301)
    }
    // cfworker 会把路径中的 `//` 合并成 `/`
    path = urlObj.href.substr(urlObj.origin.length + PREFIX.length).replace(/^https?:\/+/, 'https://')
    if (path.search(exp1) === 0 || path.search(exp5) === 0 || path.search(exp6) === 0 || path.search(exp3) === 0 || path.search(exp4) === 0) {
        return httpHandler(req, path)
    } else if (path.search(exp2) === 0) {
        if (Config.jsdelivr) {
            const newUrl = path.replace('/blob/', '@').replace(/^(?:https?:\/\/)?github\.com/, 'https://cdn.jsdelivr.net/gh')
            return Response.redirect(newUrl, 302)
        } else {
            path = path.replace('/blob/', '/raw/')
            return httpHandler(req, path)
        }
    } else if (path.search(exp4) === 0) {
        const newUrl = path.replace(/(?<=com\/.+?\/.+?)\/(.+?\/)/, '@$1').replace(/^(?:https?:\/\/)?raw\.(?:githubusercontent|github)\.com/, 'https://cdn.jsdelivr.net/gh')
        return Response.redirect(newUrl, 302)
    } else {
        return fetch(ASSET_URL + path)
    }
}

/**
 * @param {Request} req
 * @param {string} pathname
 */
function httpHandler(req, pathname) {
    const reqHdrRaw = req.headers

    // preflight
    if (req.method === 'OPTIONS' &&
        reqHdrRaw.has('access-control-request-headers')
    ) {
        return new Response(null, PREFLIGHT_INIT)
    }

    const reqHdrNew = new Headers(reqHdrRaw)

    let urlStr = pathname
    let flag = !Boolean(whiteList.length)
    for (let i of whiteList) {
        if (urlStr.includes(i)) {
            flag = true
            break
        }
    }
    if (!flag) {
        return new Response("blocked", {status: 403})
    }
    if (urlStr.search(/^https?:\/\//) !== 0) {
        urlStr = 'https://' + urlStr
    }
    const urlObj = newUrl(urlStr)

    /** @type {RequestInit} */
    const reqInit = {
        method: req.method,
        headers: reqHdrNew,
        redirect: 'manual',
        body: req.body
    }
    return proxy(urlObj, reqInit)
}

/**
 *
 * @param {URL} urlObj
 * @param {RequestInit} reqInit
 */
async function proxy(urlObj, reqInit) {
    const res = await fetch(urlObj.href, reqInit)
    const resHdrOld = res.headers
    const resHdrNew = new Headers(resHdrOld)

    const status = res.status

    if (resHdrNew.has('location')) {
        let _location = resHdrNew.get('location')
        if (checkUrl(_location))
            resHdrNew.set('location', PREFIX + _location)
        else {
            reqInit.redirect = 'follow'
            return proxy(newUrl(_location), reqInit)
        }
    }
    resHdrNew.set('access-control-expose-headers', '*')
    resHdrNew.set('access-control-allow-origin', '*')

    resHdrNew.delete('content-security-policy')
    resHdrNew.delete('content-security-policy-report-only')
    resHdrNew.delete('clear-site-data')

    return new Response(res.body, {
        status,
        headers: resHdrNew,
    })
}

第 5 步：理解两个关键配置（重要）

粘贴完代码，别急着走，有两个变量跟你的实际用法强相关，我拆开讲：

ASSET_URL：静态资源地址（实际上就是 Worker 自带的那个"输入框单页"前端页面）。默认指向项目官方页面，一般不用改。
PREFIX：访问前缀。默认根路径下是 "/"。如果你打算把镜像站挂在子路径下（比如自定义域名为 example.com/gh/*），就要把 PREFIX 改成 '/gh/'——注意，少一个斜杠都会出错！

改完代码后，点击部署 / Deploy。

第 6 步：确认部署成功

部署后，如果代码正常，右侧预览区会显示 gh-proxy 的首页（一个可以输入 GitHub 链接的搜索框页面）。到这里，镜像站核心功能已经能用了。

绑定自定义域名

默认的 workers.dev 地址也能用，但如果你想要更稳定的国内访问体验，建议绑定自己的域名。

回到 Worker 的设置页面，找到 域和路由 / Domains & Routes，点 添加 / Add。

选择 添加自定义域 / Add Custom Domain，填入你想用的域名（如 gh.你的域名.com）。

等 DNS 和证书配置生效，成功后就能通过自定义域名访问镜像站了。

怎么使用镜像站

搭好之后，用法很简单：把原本要下载的 GitHub 链接，拼到你的镜像站地址后面。

比如镜像站是 https://gh.你的域名.com/，原本要访问：

纯文本

https://github.com/用户名/仓库/releases/download/v1.0/xxx.tar.gz

就改成：

纯文本

https://gh.你的域名.com/https://github.com/用户名/仓库/releases/download/v1.0/xxx.tar.gz

很多支持自定义源的脚本、包管理器，也能把下载源指到你的镜像站，从而绕开直连问题。

常见问题与排错

1. 部署后访问页面报错 / 不是 gh-proxy 首页

检查代码是否完整替换了默认模板，有没有粘贴不全。
检查 PREFIX 是否和你的实际路径匹配。

2. 用子路径（如 /gh/）时下载失败

大概率是 PREFIX 没改对。确认代码里 PREFIX = '/gh/'（前后都有斜杠），并且你访问时也带上了 /gh/ 前缀。

3. 某些链接能转不能下 / 403

代码里有 whiteList（白名单）机制，默认空表示全部放行。如果你改过白名单，注意别把自己要下的链接挡了。

4. 自定义域名访问慢或打不开

先确认 DNS 已生效、证书正常（刚绑定可能有短暂等待）。
也可以先用默认的 workers.dev 地址排查是否是域名问题。

我的结论

这套 gh-proxy + Cloudflare Worker 的方案，是我用过最省心的 GitHub 加速镜像搭建方式——不用自己养服务器，Cloudflare 免费额度够个人用，代码复制粘贴就能跑。对经常因为 GitHub 下载超时、脚本拉取失败而头大的朋友来说，能省下不少折腾时间。

它的适用场景很聚焦，就是给"从 GitHub 下载/拉取文件"加速。如果你需要的是浏览 GitHub 网页本身更快，那是另一类方案。但就"脚本能顺利跑起来、文件能顺利下载"这个刚需来说，它足够好用。建议按步骤配一个，一劳永逸。