Pitfall record: Go compilation error in an isolated intranet environment without external network access.cannot find module

Problem Background

At Intranet isolation; connection to external networks is prohibited. environment (such as VDI virtual desktops, enterprise intranet server rooms, physically isolated servers, etc.) for Go project development, synchronize code locally to a remote Linux server through the File Transfer feature in IDEA. The remote server Absolutely no external network access, and the dependencies under the project root directory vendor Table of contents.

When executing the compilation script, the terminal throws the following error:

pkg/core/client/utils/download_files.go:13:2: cannot find module providing package golang.org/x/net/html: import lookup disabled by -mod=vendor
	(Go version in go.mod is at least 1.14 and vendor directory exists.)

Error cause analysis

The core of this error lies in Dependency lookup mechanism of the Go compiler and IDE file synchronization is incomplete conflict between.

• Default behavior of Go 1.14+: When the project root directory contains vendor Table of contents, and go.mod When the Go version declared in it is greater than or equal to 1.14, the Go compiler enables it by default.-mod=vendor Mode. Compiler Force only from vendor Find dependencies in the directory, ignore all other caches.

• Intranet isolation and file synchronization: Because the remote server strictly prohibits external network access, dependencies cannot be downloaded. And syncing thousands of via IDEA File Transfer vendor When handling small files in a directory, timeouts, lag, or missed transfers are very likely to occur.

• Final result: Compiler at vendor Some packages were found in the directory, but the exact ones were missing.golang.org/x/net/html source code file, causing an error.

Solution (only for environments without external network access)

In an offline isolated environment, any command that attempts to pull or regenerate dependencies over the network (such as go mod download,go mod vendor）are all in vain.The only solution is to ensure the local complete vendor The directory was 100% transferred to the server.

Option 1: Compressed package transfer method (most reliable, most recommended)

Do not use the file synchronization of the IDE to transfer.vendor A directory with tens of thousands of small files will definitely cause problems. Please take the following steps:

• Local packaging: On your local development machine (Windows/Mac), take the complete vendor Directory compressed to vendor.zip or vendor.tar.gz.

• Single file upload: Use tools such as Xftp and WinSCP to upload the compressed package to the project root directory on the server.

• Remote extraction and overwrite:

cd /path/to/your/project
rm -rf vendor        # Delete the incomplete vendor on the server
unzip vendor.zip     # or tar -zxvf vendor.tar.gz

Option 2: IDEA forced comparison synchronization (suitable when only a few files differ)

If you are sure that only a few files were missed in the upload, you can try forcing synchronization through the IDE.

• In IDEA, right-click the project root directory.

• Select Deployment->Sync with Deployed to....

• Carefully check the difference list on the right, confirm the missing files, and click upload.

💡 Pitfall-avoidance tips for intranet-isolated/offline development environments

• Block vendor automatic synchronization: In IDEA, right-click vendor Table of Contents Mark Directory as -> Excluded. In daily development, only synchronize the source code you modified (.go file), do not let the IDE touch the huge vendor.

• Dependency update process: Every time it is updated locally go.mod, local execution completed go mod vendor Afterwards, directly package the entire vendor Transfer directory to server.Never rely on the incremental sync of the IDE to transfer dependencies.

• Intranet GOPROXY (Advanced): If other developer colleagues on the intranet also face this problem, you can find a machine on the intranet with network access to set up a private GOPROXY (such as Athens), or directly $GOPATH/pkg/mod Package the directory and copy it over, completely say goodbye to vendor the torment of.