Справочник go.mod файла

Каждый Go модуль определяется файлом go.mod, который описывает свойства модуля, включая его зависимости от других модулей и от версий Go.

Эти свойства включают:

Путь модуля текущего модуля. Это должен быть путь, по которому модуль может быть загружен инструментами Go, например, расположение репозитория кода модуля. Он служит уникальным идентификатором, когда комбинируется с номером версии модуля. Также он является префиксом пути пакета для всех пакетов в модуле. Подробнее о том, как Go находит модуль, см. Справочник по Go Modules.
Минимальная версия Go, необходимая для текущего модуля.
Список минимальных версий других модулей, необходимых текущему модулю.
Инструкции, при необходимости, заменить требуемый модуль другой версией модуля или локальной директорией, или исключить конкретную версию требуемого модуля.

Go генерирует файл go.mod при выполнении команды go mod init. В следующем примере создается файл go.mod, устанавливая путь модуля в example/mymodule:

<code>$ go mod init example/mymodule
</code>

Используйте команды go для управления зависимостями. Эти команды обеспечивают соответствие требований, описанных в вашем go.mod файле, и корректность содержимого файла go.mod. К этим командам относятся go get, go mod tidy и go mod edit.

Для справки по командам go см. Команда go. Справку по командам можно получить из командной строки, набрав go help command-name, например, go help mod tidy.

См. также

Go инструменты вносят изменения в ваш go.mod файл по мере использования для управления зависимостями. Подробнее см. Управление зависимостями.
Для получения дополнительных сведений и ограничений, связанных с go.mod файлами, см. Справочник по Go модулям.

Пример

Файл go.mod включает директивы, как показано в следующем примере. Они описаны ниже в этом разделе.

<code>module example.com/mymodule

go 1.14

require (
  example.com/othermodule v1.2.3
  example.com/thismodule v1.2.3
  example.com/thatmodule v1.2.3
)

replace example.com/thatmodule => ../thatmodule
exclude example.com/thismodule v1.3.0
</code>

module

Объявляет путь модуля, который является уникальным идентификатором модуля (в сочетании с номером версии модуля). Путь модуля становится префиксом импорта для всех пакетов, содержащихся в модуле.

Для дополнительной информации см. директиву module в Справочнике по Go Modules.

Синтаксис

module <var>module-path</var>

module-path: Путь модуля, обычно это расположение репозитория, из которого Go-инструменты могут загрузить модуль. Для версий модулей v2 и выше, это значение должно заканчиваться номером основной версии, например, /v2.

Примеры

Следующие примеры заменяют example.com на домен репозитория, из которого может быть загружен модуль.

Объявление модуля для v0 или v1 модуля:
```
<code>module example.com/mymodule
</code>
```
Путь модуля для v2 модуля:
```
<code>module example.com/mymodule/v2
</code>
```

Примечания

Путь модуля должен уникально идентифицировать ваш модуль. Для большинства модулей путь представляет собой URL, по которому команда go может найти код (или перенаправление на код). Для модулей, которые никогда не будут загружаться напрямую, путь модуля может быть просто названием, которым вы управляете, обеспечивающим уникальность. Префикс example/ также зарезервирован для использования в примерах, подобных этим.

За дополнительной информацией обращайтесь к разделу Управление зависимостями.

На практике путь модуля обычно является доменом репозитория исходного кода модуля и путём к коду модуля внутри репозитория. Команда go полагается на этот формат при загрузке версий модулей для разрешения зависимостей от имени пользователя модуля.

Даже если вы изначально не планируете делать ваш модуль доступным для использования из другого кода, использование пути репозитория является лучшей практикой, которая поможет вам избежать необходимости переименовывать модуль, если вы опубликуете его позже.

Если вы пока не знаете окончательного местоположения репозитория модуля, рассмотрите возможность временного использования безопасной замены, такой как имя домена, которым вы владеете, или имя, которым вы управляете (например, название вашей компании), а также путь, следующий за названием модуля или исходной директорией. За дополнительной информацией обращайтесь к разделу Управление зависимостями.

Например, если вы разрабатываете в директории stringtools, ваш временный путь модуля может быть <company-name>/stringtools, как в следующем примере, где company-name — это название вашей компании:

<code>go mod init <company-name>/stringtools
</code>

go

Указывает, что модуль был написан с предположением о семантике версии Go, указанной директивой.

За дополнительной информацией обращайтесь к разделу go директива в Справочнике по Go Modules.

Синтаксис

go <var>minimum-go-version</var>

minimum-go-version: Минимальная версия Go, необходимая для компиляции пакетов в этом модуле.

Примеры

Модуль должен работать на Go версии 1.14 или выше:
```
<code>go 1.14
</code>
```

Примечания

Директива go задаёт минимальную версию Go, необходимую для использования этого модуля. До Go 1.21 директива была только рекомендательной; теперь она является обязательным требованием: инструментарий Go отказывается использовать модули, объявляющие более новые версии Go.

Директива go служит входными данными для выбора используемого инструментария Go. Подробности см. в разделе "Инструментарии Go".

Директива go влияет на использование новых языковых возможностей:

Для пакетов внутри модуля компилятор запрещает использование языковых возможностей, введённых после версии, указанной директивой go. Например, если модуль имеет директиву go 1.12, его пакеты не могут использовать числовые литералы вроде 1_000_000, которые были введены в Go 1.13.
Если более старая версия Go собирает один из пакетов модуля и сталкивается с ошибкой компиляции, ошибка указывает, что модуль был написан для более новой версии Go. Например, предположим, что модуль имеет go 1.13, а пакет использует числовой литерал 1_000_000. Если этот пакет собирается с использованием Go 1.12, компилятор указывает, что код написан для Go 1.13.

Директива go также влияет на поведение команды go:

Начиная с версии go 1.14, может быть включено автоматическое вендоринг. Если файл vendor/modules.txt существует и соответствует go.mod, не требуется явно использовать флаг -mod=vendor.
Начиная с версии go 1.16, шаблон пакета all соответствует только пакетам, транзитивно импортируемым пакетами и тестами в основном модуле. Это тот же набор пакетов, который сохраняется командой go mod vendor с момента появления модулей. В более ранних версиях all также включал тесты пакетов, импортируемых пакетами основного модуля, тесты этих пакетов и так далее.
Начиная с версии go 1.17:
- Файл go.mod включает явную директиву require для каждого модуля, который предоставляет любой пакет, транзитивно импортируемый пакетом или тестом в основном модуле. (В версиях go 1.16 и ниже, косвенная зависимость включается только если выбор минимальной версии в противном случае выбрал бы другую версию.) Эта дополнительная информация позволяет выполнять сокращение графа модулей и ленивую загрузку модулей.
- Поскольку количество // indirect зависимостей может быть гораздо больше, чем в предыдущих версиях go, косвенные зависимости записываются в отдельный блок внутри файла go.mod.
- go mod vendor исключает файлы go.mod и go.sum для зависимостей, находящихся в каталоге vendor. (Это позволяет вызовам команды go внутри подкаталогов vendor определять корректный основной модуль.)
- go mod vendor записывает версию go из файла go.mod каждой зависимости в vendor/modules.txt.
Начиная с версии go 1.21:
- Строка go объявляет минимально требуемую версию Go для использования с этим модулем.
- Строка go должна быть больше или равна строке go всех зависимостей.
- Команда go больше не пытается поддерживать совместимость со старой предыдущей версией Go.
- Команда go более осторожно обращается с хэш-суммами файлов go.mod в файле go.sum.

Файл go.mod может содержать не более одной директивы go. Большинство команд добавят директиву go с текущей версией Go, если такой директивы ещё нет.

toolchain

Объявляет рекомендуемую версию инструментария Go для использования с этим модулем. Действует только тогда, когда модуль является основным и инструментарий по умолчанию старше рекомендуемого.

Для получения дополнительной информации см. раздел «Go toolchains» и toolchain directive в справочнике по Go Modules.

Синтаксис

toolchain <var>toolchain-name</var>

toolchain-name: Имя рекомендуемого инструментария Go. Стандартные имена инструментариев имеют вид goV для версии Go V, например, go1.21.0 и go1.18rc1. Специальное значение default отключает автоматическую смену инструментария.

Примеры

Рекомендация использовать Go 1.21.0 или новее:
```
<code>toolchain go1.21.0
</code>
```

Примечания

См. раздел «Go toolchains» для подробного описания того, как строка toolchain влияет на выбор инструментария Go.

godebug

Указывает значения GODEBUG по умолчанию, которые будут применяться к основным пакетам этого модуля. Они переопределяют значения по умолчанию инструментария и переопределяются явными строками //go:debug в основных пакетах.

Синтаксис

godebug <var>debug-key</var>=<var>debug-value</var>

debug-key: Имя настройки, которая будет применена. Список настроек и версий, с которых они были представлены, можно найти на странице GODEBUG History.
debug-value: Значение, указанное для параметра. Если иное не указано, 0 для отключения и 1 для включения указанного поведения.

Примеры

Использование нового поведения asynctimerchan=0 из Go 1.23:
```
<code>godebug asynctimerchan=0
</code>
```
Использование стандартных значений GODEBUG из Go 1.21, но старого поведения panicnil=1:
```
<code>godebug (
  default=go1.21
  panicnil=1
)
</code>
```

Примечания

Настройки GODEBUG применяются только к сборкам основных пакетов и тестовых бинарных файлов в текущем модуле. Они не имеют никакого эффекта, когда модуль используется как зависимость.

См. раздел “Go, обратная совместимость и GODEBUG” для получения подробной информации о совместимости.

require

Объявляет модуль как зависимость текущего модуля, указывая минимальную версию модуля, необходимую для работы.

Более подробную информацию см. в разделе require директива в справочнике по Go Modules.

Синтаксис

require <var>module-path</var> <var>module-version</var>

module-path: Путь модуля, обычно представляет собой комбинацию домена репозитория исходного кода модуля и его имени. Для версий модулей v2 и выше, это значение должно заканчиваться номером основной версии, например /v2.
module-version: Версия модуля. Может быть либо номером релиза, таким как v1.2.3, либо псевдо-версией, сгенерированной Go-инструментами, например v0.0.0-20200921210052-fa0125251cc4.

Примеры

Требование релизной версии v1.2.3:
```
<code>require example.com/othermodule v1.2.3
</code>
```
Требование версии, ещё не помеченной в репозитории, с использованием псевдо-версии, сгенерированной инструментами Go:
```
<code>require example.com/othermodule v0.0.0-20200921210052-fa0125251cc4
</code>
```

Примечания

Когда вы запускаете команду go, например go get, Go автоматически добавляет директивы require для каждого модуля, содержащего импортируемые пакеты. Если модуль ещё не помечен в репозитории, Go присваивает ему псевдо-версию, которая генерируется при запуске команды.

Вы можете заставить Go требовать модуль из другого места, отличного от его репозитория, используя replace директиву.

Для получения дополнительной информации о номерах версий см. Нумерация версий модулей.

Для получения информации о управлении зависимостями см. следующее:

tool

Добавляет пакет в качестве зависимости текущего модуля и делает его доступным для запуска с помощью go tool, когда текущий рабочий каталог находится внутри этого модуля.

Синтаксис

tool <var>package-path</var>

package-path: Путь к пакету инструмента, который представляет собой конкатенацию пути модуля, содержащего инструмент, и (возможно, пустого) пути к пакету, реализующему инструмент внутри модуля.

Примеры

Объявление инструмента, реализованного в текущем модуле:
```
<code>module example.com/mymodule

tool example.com/mymodule/cmd/mytool
</code>
```

Объявление инструмента, реализованного в отдельном модуле:

<code>module example.com/mymodule

tool example.com/atool/cmd/atool

require example.com/atool v1.2.3
</code>

Примечания

Вы можете использовать go tool для запуска инструментов, объявленных в вашем модуле, указав полный путь к пакету или, если нет неоднозначности, последний сегмент пути. В первом примере выше вы можете выполнить go tool mytool или go tool example.com/mymodule/cmd/mytool.

В режиме рабочего пространства вы можете использовать go tool для запуска инструмента, объявленного в любом модуле рабочего пространства.

Инструменты собираются с использованием того же графа модулей, что и сам модуль. Для выбора версии модуля, реализующего инструмент, требуется директива require. Любые директивы replace или exclude также применяются к инструменту и его зависимостям.

Для получения дополнительной информации см. Зависимости инструментов.

replace

Заменяет содержимое модуля на определённой версии (или всех версиях) другим модулем или локальной директорией. Инструменты Go будут использовать путь замены при разрешении зависимости.

Для получения дополнительной информации см. директиву replace в справочнике по Go Modules.

Синтаксис

replace <var>module-path</var> <var>[module-version]</var> => <var>replacement-path</var> <var>[replacement-version]</var>

module-path: Путь к модулю, который нужно заменить.
module-version: Необязательно. Конкретная версия для замены. Если номер версии опущен, все версии модуля заменяются содержимым, указанным справа от стрелки.
replacement-path: Путь, по которому Go должно искать требуемый модуль. Это может быть путь к модулю или путь к директории на локальной файловой системе относительно заменяющего модуля. Если это путь к модулю, необходимо указать значение replacement-version. Если это локальный путь, значение replacement-version использовать нельзя.
replacement-version: Версия заменяющего модуля. Версию замены можно указать только в том случае, если replacement-path является путём модуля (а не локальной директорией).

Примеры

Замена с использованием форка репозитория модуля

В следующем примере любая версия example.com/othermodule заменяется на указанный форк его кода.
```
<code>require example.com/othermodule v1.2.3

replace example.com/othermodule => example.com/myfork/othermodule v1.2.3-fixed
</code>
```
Когда вы заменяете один путь модуля другим, не изменяйте инструкции импорта для пакетов в модуле, который вы заменяете.

Для получения дополнительной информации о использовании форка кода модуля, см. Требование внешнего кода модуля из вашего собственного форка репозитория.
Замена с использованием другого номера версии

В следующем примере указывается, что версия v1.2.3 должна использоваться вместо любой другой версии модуля.
```
<code>require example.com/othermodule v1.2.2

replace example.com/othermodule => example.com/othermodule v1.2.3
</code>
```
Следующий пример заменяет версию модуля v1.2.5 на версию v1.2.3 того же модуля.
```
<code>replace example.com/othermodule v1.2.5 => example.com/othermodule v1.2.3
</code>
```
Замена с использованием локального кода

Следующий пример указывает, что локальная директория должна использоваться как замена для всех версий модуля.
```
<code>require example.com/othermodule v1.2.3

replace example.com/othermodule => ../othermodule
</code>
```
Следующий пример указывает, что локальная директория должна использоваться как замена только для версии v1.2.5.
```
<code>require example.com/othermodule v1.2.5

replace example.com/othermodule v1.2.5 => ../othermodule
</code>
```
Для получения дополнительной информации о использовании локальной копии кода модуля, см. Требование кода модуля в локальной директории.

Примечания

Используйте директиву replace для временной замены значения пути модуля другим значением, когда вы хотите, чтобы Go использовал другой путь для поиска исходного кода модуля. Это приводит к перенаправлению поиска модуля Go в местоположение замены. Не требуется изменять пути импорта пакетов для использования пути замены.

Используйте директивы exclude и replace для управления разрешением зависимостей во время сборки при сборке текущего модуля. Эти директивы игнорируются в модулях, которые зависят от текущего модуля.

Директива replace может быть полезна в следующих ситуациях:

Вы разрабатываете новый модуль, код которого ещё не находится в репозитории. Вы хотите протестировать его с клиентами, используя локальную версию.
Вы обнаружили проблему с зависимостью, клонировали репозиторий зависимости и тестируете исправление с использованием локального репозитория.

Обратите внимание, что сама по себе директива replace не добавляет модуль в граф модулей. Директива require необходима для этого.

Также требуется указать версию заменяемого модуля, либо в файле go.mod основного модуля, либо в файле go.mod зависимости. Если вы не знаете, какую конкретную версию заменить, можно использовать фейковую версию, как в примере ниже. Обратите внимание, что это приведёт к разрыву зависимостей у модулей, которые зависят от вашего модуля, поскольку директивы replace применяются только в основном модуле.

<code>require example.com/mod v0.0.0-replace

replace example.com/mod v0.0.0-replace => ./mod
</code>

Для получения дополнительной информации о замене требуемого модуля, включая использование инструментов Go для внесения изменений, см.:

Для получения дополнительной информации о номерах версий см. Нумерация версий модулей.

exclude

Указывает модуль или версию модуля, которые следует исключить из графа зависимостей текущего модуля.

Для получения дополнительной информации см. директиву exclude в Справочнике по Go Modules.

Синтаксис

exclude <var>module-path</var> <var>module-version</var>

module-path: Путь к модулю, который нужно исключить.
module-version: Конкретная версия, которую нужно исключить.

Пример

Исключить версию v1.3.0 модуля example.com/theirmodule
```
<code>exclude example.com/theirmodule v1.3.0
</code>
```

Примечания

Директива exclude используется для исключения конкретной версии модуля, который требуеться косвенно, но не может быть загружен по какой-либо причине. Например, можно использовать её для исключения версии модуля с недействительной контрольной суммой.

Директивы exclude и replace позволяют управлять разрешением зависимостей во время сборки при сборке текущего модуля (основного модуля, который вы собираете). Эти директивы игнорируются в модулях, которые зависят от текущего модуля.

Можно использовать команду go mod edit для исключения модуля, как в следующем примере.

<code>go mod edit -exclude=example.com/theirmodule@v1.3.0
</code>

Для получения дополнительной информации о номерах версий см. Нумерация версий модулей.

retract

Указывает, что версия или диапазон версий модуля, определённого в go.mod, не должна использоваться в зависимостях. Директива retract полезна, когда версия была опубликована преждевременно или обнаружена серьёзная проблема после публикации версии.

Для получения дополнительной информации см. директиву retract в Справочнике по Go Modules.

Синтаксис

retract <var>version</var> // <var>rationale</var>
retract [<var>version-low</var>,<var>version-high</var>] // <var>rationale</var>

version: Одна версия для отката.
version-low: Нижняя граница диапазона версий для отката.
version-high: Верхняя граница диапазона версий для отката. И version-low, и version-high включены в диапазон.
rationale: Необязательный комментарий, объясняющий откат. Может отображаться в сообщениях для пользователя.

Пример

Откат одной версии

<code>retract v1.1.0 // Опубликовано по ошибке.
</code>

Откат диапазона версий

<code>retract [v1.0.0,v1.0.5] // Сборка сломана на некоторых платформах.
</code>

Примечания

Используйте директиву retract, чтобы указать, что предыдущая версия вашего модуля не должна использоваться. Пользователи не будут автоматически обновляться до откращенной версии с помощью команд go get, go mod tidy или других. Откращенная версия не будет отображаться как доступное обновление при использовании go list -m -u.

Откращенные версии должны оставаться доступными, чтобы пользователи, которые уже зависят от них, могли собирать свои пакеты. Даже если откращенная версия удалена из исходного репозитория, она может остаться доступной на зеркалах, таких как proxy.golang.org. Пользователи, которые зависят от откращенных версий, могут получать уведомления при запуске команд go get или go list -m -u для связанных модулей.

Команда go обнаруживает откращенные версии, читая директивы retract в файле go.mod в последней версии модуля. Последняя версия определяется в порядке приоритета:

Её самая высокая версия релиза, если такая имеется
Её самая высокая предрелизная версия, если такая имеется
Псевдо-версия для последнего коммита ветки по умолчанию репозитория.

Когда вы добавляете откат, почти всегда необходимо тегировать новую, более высокую версию, чтобы команда могла увидеть её в последней версии модуля.

Можно опубликовать версию, единственной целью которой является сигнализация об откатах. В этом случае новая версия также может откатывать саму себя.

Например, если вы случайно тегировали v1.0.0, вы можете тегировать v1.0.1 с следующими директивами:

<code>retract v1.0.0 // Опубликовано по ошибке.
retract v1.0.1 // Содержит только откат.
</code>

К сожалению, как только версия опубликована, её нельзя изменить. Если позже вы тегируете v1.0.0 в другом коммите, команда go может обнаружить несоответствие хэша в go.sum или в базе данных хэшей.

Откращенные версии модуля обычно не отображаются в выводе команды go list -m -versions, но вы можете использовать флаг -retracted, чтобы отобразить их. Подробнее см. в разделе go list -m в Справочнике по Go Modules.