# next-go-modules

**Repository Path**: normalcoder/next-go-modules

## Basic Information

- **Project Name**: next-go-modules
- **Description**: 为 Next.js 13+ 设计的 Go Modules 代理中间件，完美支持 Vercel。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://www.npmjs.com/package/next-go-modules
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-18
- **Last Updated**: 2025-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: nextjs, go-modules, next-middleware, go-proxy

## README

# next-go-modules

![NPM Version](https://img.shields.io/npm/v/next-go-modules)
[![LICENSE](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
![Top language](https://img.shields.io/github/languages/top/normal-coder/next-go-modules)

![social preview for next-go-modules](./images/next-go-modules.png)

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

[English](./README.md) | [中文](./README.zh-cn.md)

## 功能特性

- ✅ 开箱即用，配置简单
- ✅ 支持开发者个性化 Go Modules 地址，支持别名
- ✅ 摆脱 Nginx 依赖，完美支持 Vercel 部署
- ✅ 最低兼容 Next.js 13
- ✅ TypeScript 支持，可配置缓存，支持调试模式

## 安装

```bash
# npm
npm install next-go-modules

# yarn
yarn add next-go-modules

# pnpm
pnpm add next-go-modules
```

## 快速开始

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

```bash
# 自动生成所有必要文件
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. 创建模块配置

```typescript
// 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. 创建中间件

```typescript
// 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 goModulesMiddleware

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

#### 3. 创建 API 路由

```typescript
// 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：

```typescript
// 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 模块：

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

## 配置选项

### GoModule

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

### GoModulesConfig

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

### MiddlewareOptions

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

## 高级用法

### 自定义 API 路由

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

### 自定义缓存控制

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

### 自定义匹配器

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

### 调试模式

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

### 与现有中间件集成

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

```typescript
// 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
)
```

## 开发贡献

### 开发环境设置

```bash
# 克隆仓库
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](https://conventionalcommits.org/) 规范：

```bash
# 使用 commitizen 交互式提交
pnpm commit

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

### 版本发布

使用 [Changesets](https://github.com/changesets/changesets) 管理版本：

```bash
# 添加变更记录
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](https://nextjs.org/) - React 全栈框架
- [TypeScript](https://www.typescriptlang.org/)
- [ESLint](https://eslint.org/)
- [Husky](https://typicode.github.io/husky/)
- [Changesets](https://github.com/changesets/changesets)
- [Commitizen](https://commitizen-tools.github.io/commitizen/)

## 许可证

MIT 许可证 - 详见 [LICENSE](./LICENSE) 文件。