README.zh-cn.md

next-go-modules

为 Next.js 13+ 设计的 Go Modules 代理中间件，完美支持 Vercel。

English | 中文

功能特性

• ✅ 开箱即用，配置简单
• ✅ 支持开发者个性化 Go Modules 地址，支持别名
• ✅ 摆脱 Nginx 依赖，完美支持 Vercel 部署
• ✅ 兼容 Next.js 13.0+ (App Router 和 Pages Router)
• ✅ TypeScript 支持，可配置缓存，支持调试模式
• ✅ 跨版本兼容（避免 Next.js 类型冲突）

安装

# npm
npm install next-go-modules

# yarn
yarn add next-go-modules

# pnpm
pnpm add next-go-modules

快速开始

方式一：使用 CLI 工具（推荐）

# 自动生成所有必要文件
npx next-go-modules init

# 或者如果已全局安装
next-go-modules init

这将自动创建：

• config/go-modules.ts - 模块配置文件
• middleware.ts - Next.js 中间件
• API 路由文件（根据项目结构自动选择 App Router 或 Pages Router）

然后编辑 config/go-modules.ts 添加你的 Go 模块配置即可。

Note

如果项目中已存在 middleware.ts，CLI 工具会提供集成指导而不会覆盖现有文件。

方式二：手动配置

1. 创建模块配置

// config/go-modules.ts
import { GoModulesConfig } from 'next-go-modules'

export const goModulesConfig: GoModulesConfig = {
  modules: {
    'my-go-tool': {
      name: 'my-go-tool',
      fullName: 'yourdomain.com/my-go-tool',
      repo: 'https://github.com/yourusername/my-go-tool',
      description: 'A useful Go tool',
      install: 'go get -u yourdomain.com/my-go-tool',
      version: 'v1.0.0',
      aliases: ['tool'], // 可选别名，支持 go get -u yourdomain.com/tool
    },
    // 在此添加更多模块...
  },
}

2. 创建中间件

方式 A：使用辅助函数（推荐用于 Next.js 15）

// src/middleware.ts (如果使用 src 目录) 或 middleware.ts (项目根目录)
import { createGoModulesMiddleware } from 'next-go-modules'
import { goModulesConfig } from './config/go-modules'

const goModulesMiddleware = createGoModulesMiddleware({
  config: goModulesConfig,
  debug: process.env.NODE_ENV === 'development',
})

export default function middleware(request: any) {
  return goModulesMiddleware(request)
}

export const config = {
  matcher: [
    '/((?!api|_next/static|_next/image|favicon.ico|manifest.webmanifest|sitemap.xml).*)',
  ],
}

3. 创建 API 路由

// app/api/go-modules/[...module]/route.ts (App Router)
import { createGoModulesApiRoute, createGoModulesHeadRoute } from 'next-go-modules'
import { goModulesConfig } from '../../../../config/go-modules'

export const GET = createGoModulesApiRoute(goModulesConfig)
export const HEAD = createGoModulesHeadRoute(goModulesConfig)

或者使用 Pages Router：

// pages/api/go-modules/[...module].ts (Pages Router)
import { createGoModulesApiRoute } from 'next-go-modules'
import { goModulesConfig } from '../../../config/go-modules'

export default createGoModulesApiRoute(goModulesConfig)

使用方法

现在你的 Go 模块可以通过以下路径访问：

• /my-go-tool - 主路径
• /tool - 别名路径
• /my-go-tool?go-get=1 - 带 go-get 参数

用户可以通过以下命令安装你的 Go 模块：

go get -u yourdomain.com/my-go-tool

配置选项

GoModule

interface GoModule {
  name: string // 模块名称
  fullName: string // 完整模块路径（如：'example.com/module'）
  repo: string // 仓库 URL
  description: string // 模块描述
  install: string // 安装命令
  tags?: string[] // 可选标签
  version?: string // 可选版本
  aliases?: string[] // 可选别名
}

GoModulesConfig

interface GoModulesConfig {
  modules: Record<string, GoModule>
  apiRoute?: string // 默认：'/api/go-modules'
  matcher?: string[] // 默认：排除静态文件
  cacheControl?: string // 默认：'public, max-age=3600'
}

MiddlewareOptions

interface MiddlewareOptions {
  config: GoModulesConfig
  debug?: boolean // 启用调试日志
}

高级用法

自定义 API 路由

const config: GoModulesConfig = {
  modules: { /* 你的模块 */ },
  apiRoute: '/api/custom-go-modules',
}

自定义缓存控制

const config: GoModulesConfig = {
  modules: { /* 你的模块 */ },
  cacheControl: 'public, max-age=7200', // 2 小时
}

自定义匹配器

const config: GoModulesConfig = {
  modules: { /* 你的模块 */ },
  matcher: [
    '/((?!api|_next|favicon.ico).*)',
  ],
}

调试模式

const middleware = createGoModulesMiddleware({
  config: goModulesConfig,
  debug: true, // 启用控制台日志
})

与现有中间件集成

如果你已经有了中间件，可以使用组合函数：

// middleware.ts
import { composeMiddleware, createGoModulesMiddleware } from 'next-go-modules'
import { goModulesConfig } from './config/go-modules'

// 你现有的中间件
function yourExistingMiddleware(request) {
  // 你的逻辑
}

// Go 模块中间件
const goModulesMiddleware = createGoModulesMiddleware({
  config: goModulesConfig,
  debug: process.env.NODE_ENV === 'development',
})

// 组合中间件
export default composeMiddleware(
  goModulesMiddleware,
  yourExistingMiddleware
)

开发贡献

开发环境设置

# 克隆仓库
git clone https://github.com/normal-coder/next-go-modules.git
cd next-go-modules

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 代码检查
pnpm lint

# 构建
pnpm build

提交规范

本项目使用 Conventional Commits 规范：

# 使用 commitizen 交互式提交
pnpm commit

# 或手动符合格式
git commit -m "feat: add new feature"
git commit -m "fix: resolve issue"
git commit -m "docs: update readme"

版本发布

使用 Changesets 管理版本：

# 添加变更记录
pnpm changeset

# 更新版本
pnpm version

# 发布到 npm
pnpm release

贡献流程

1. Fork 仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (pnpm commit)
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

致谢

• Next.js - React 全栈框架
• TypeScript
• ESLint
• Husky
• Changesets
• Commitizen

许可证

MIT 许可证 - 详见 LICENSE 文件。