编程语言环境搭建汇总(AI)

2026-01-13

AIcoding>AI编程知识>编程语言

39k words

编程语言环境搭建汇总(AI)

下面给你一份「从 0 到可运行」的代码运行环境搭建全流程，每个阶段都给了思考点 + 自检问题 +（可选）AI 提问模板。按照它走，基本能把任何语言/任何项目在本机与 CI 上跑起来，并做到可复现、可交接。

1) 目标与边界定义

要做什么？在什么机器上跑到什么程度才算成功？

思考点：目标平台（本机/容器/CI/云）、输入输出、端口、是否依赖外部服务（DB、MQ、缓存）。
自检问题
- 成功标准是“能启动服务并通过健康检查/样例脚本”还是“能跑完全部测试”？
- 平台与架构：Windows/macOS/Linux？x86_64/arm64？
AI 提问模板
- “给我列出把 X 项目本地跑通的最小步骤（含端口、示例命令和健康检查方式）。”

2) 基线检查（Host Readiness）

确认你的机器满足最低条件。

思考点：CPU/内存/磁盘、网络与代理、公司证书、权限（管理员/开发者模式）。
自检问题
- 是否需要企业代理/私有 CA 证书？
- 是否有 GPU / 特殊驱动（CUDA、Metal）需求？
AI 模板
- “在 macOS/Windows/Linux 上为 X 项目准备基础依赖与系统包的清单（brew/apt/choco 对照表）。”

3) 运行时与版本策略

选定语言版本与版本管理器，锁死可复现。

选型建议
- 多语言项目优先 asdf 做统一版本管理；否则：Python→pyenv/conda，Node→nvm，Java→sdkman，Go→内置。
自检问题
- 用哪一版（LTS/项目要求）？与 CI 是否一致？团队如何切换版本？
AI 模板
- “为 X 项目生成 asdf 的 .tool-versions 内容，并解释每个版本选择的理由。”

4) 包管理与依赖锁定

使用官方包管 + 锁文件，必要时加系统包。

Python：pip+venv 或 poetry（必须有 requirements.txt/poetry.lock）
Node：pnpm/yarn/npm（必须有 lockfile）
Java：Maven/Gradle（本地缓存策略）
Go：Go modules（go.mod）
C/C++：vcpkg/Conan + 系统包（OpenSSL、zlib…）
自检问题
- 是否存在本地原生扩展（需要编译器/SDK）？
- 私有源/镜像与鉴权如何配置？
AI 模板
- “请检查这份依赖清单，标出需要系统级库或本地编译器的项，并给出安装命令。”

5) 隔离策略（本地）

避免“我的电脑能跑你不行”。

选项：虚拟环境（venv/conda）、容器（Docker）、Dev Container、Nix/Guix。
原则：开发环境与 CI 尽量同构；团队交接首选 Dev Container/Nix。
自检问题
- 是否必须容器化（有原生驱动/GUI 例外）？镜像体积与构建时间是否可接受？
AI 模板
- “为 X 项目生成一个最小可用的 Dockerfile 与 .devcontainer/devcontainer.json。”

6) 构建与任务编排

统一命令入口，减少脑负担。

建议：提供 Makefile/Justfile/package.json scripts
- 常用目标：setup | dev | test | lint | build | run | clean
自检问题
- 新人克隆仓库后，一个命令能跑起来吗？（如 make dev）
AI 模板
- “根据以下项目结构生成一个跨平台的 Makefile（含 Windows 兼容提示）。”

7) 配置与密钥

12-Factor 配置：环境变量优先，拒绝硬编码。

.env.example 提供占位；本地用 .env，CI 用 Secret 管理（GitHub Actions/CI 密钥）。
自检问题
- 哪些变量是必填？有没有默认值？是否区分 dev/staging/prod？
AI 模板
- “根据项目需要生成 .env.example，并给出每个变量的说明和安全注意事项。”

8) 外部服务与数据

数据库/缓存/消息队列/对象存储等。

推荐：docker-compose 启动依赖服务，提供初始化脚本与迁移命令。
自检问题
- 本地数据如何播种（seed）？迁移/回滚命令是什么？
- 端口冲突如何避免？
AI 模板
- “为本项目生成 docker-compose.yml，包含 Postgres + Redis + MinIO，并带健康检查。”

9) 开发工具与 IDE 集成

让调试与规范“点一下就好”。

VS Code：.vscode/launch.json、.vscode/settings.json、推荐扩展列表
代码质量：pre-commit、formatter（Black/Prettier/gofmt）、linter（flake8/eslint/golangci-lint）
自检问题
- 保存即格式化？提交前自动检查？断点调试是否开箱即用？
AI 模板
- “生成 VS Code 的 launch.json，支持附加到运行中的容器内进程调试。”

10) 测试与健康检查

先有“冒烟”，再谈“覆盖”。

冒烟：curl /healthz、样例 CLI 返回码
自动化：单测→集成→端到端；数据库迁移前后跑一遍。
自检问题
- 本地一键 make test 是否稳定？随机失败点？
AI 模板
- “为 X 项目写一段最小冒烟测试脚本（bash/python），并输出可读的诊断信息。”

11) 运行与验证

如何确定“真的跑起来”？

标准：日志无错误、端口监听、健康检查 OK、关键功能手测/自动脚本通过。
自检问题
- 如何快速定位启动失败（配置/依赖/网络/权限）？
AI 模板
- “给出一个启动后 30 秒内自动验证三项功能的脚本。”

12) 观察与性能

早放探针，少背锅。

日志级别（dev：DEBUG；prod：INFO/WARN）、采样追踪（OpenTelemetry）、指标（Prometheus）、本地剖析（py-spy/pprof/JFR）。
自检问题
- 慢查询/热点函数怎么看？本地如何重现实战流量？
AI 模板
- “为服务接入 OpenTelemetry 最小示例（HTTP 入栈 + DB 出栈）。”

13) CI/CD 对齐

本地 ≈ CI，保障可复现。

步骤：checkout→缓存→设置运行时→安装依赖→构建→测试→构建镜像→安全扫描（SAST/SBOM）→产物发布。
自检问题
- 是否使用与本地相同的 Dockerfile/锁文件？缓存是否命中？
AI 模板
- “生成 GitHub Actions workflow，对 Python/Node/Go 的依赖做缓存。”

14) 文档与交接

把口头知识变脚本与文档。

README 模板建议
1. 一句话介绍与架构图
2. 快速开始（10 步内）
3. 常用命令表
4. 依赖服务与端口
5. 配置项说明
6. 故障排查（FAQ）
7. 贡献指南（Conventional Commits、代码规范）

15) 复现性与合规

可复现 = 可维护。

锁版本（lockfiles、镜像 digest）、制品仓库、镜像签名、License 合规（SBOM）、备份/恢复演练。
自检问题
- 若 6 个月后拉起同一 tag，能一次跑通吗？

「10 步极简 Checklist」（贴墙）

克隆仓库，读 README 的快速开始
安装 asdf/pyenv/nvm（或使用 Dev Container）
切到指定运行时版本
make setup（安装系统包/依赖）
准备 .env（从 .env.example 复制并填写）
docker-compose up -d 启外部服务
make dev 启动应用
make smoke 做冒烟验证
make test 跑测试 + make lint
提交前 pre-commit run -a，成功后推送/触发 CI

各语言「最小命令集」示例

Python（Poetry + venv）

asdf install python 3.11.9 && asdf local python 3.11.9
pipx install poetry
poetry install --no-root
cp .env.example .env
poetry run uvicorn app:app --reload

Node（pnpm）

corepack enable
asdf local nodejs 20.14.0
pnpm i
cp .env.example .env
pnpm dev

asdf local golang 1.22.5
go mod download
cp .env.example .env
go run ./cmd/server

Java（Gradle）

1
2
3

sdk install java 17.0.10-tem && sdk use java 17.0.10-tem
./gradlew build
java -jar build/libs/app.jar

C/C++（vcpkg + CMake）

./vcpkg/bootstrap-vcpkg.sh
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=./vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build -j
./build/bin/app

常见故障 → 快速定位

端口被占用：lsof -i :PORT / 改 .env 端口
缺系统库：根据编译错误补 apt-get install xxx-dev / brew install
证书/代理：设置 NODE_EXTRA_CA_CERTS/REQUESTS_CA_BUNDLE，或导入公司 CA
架构不匹配：arm64 vs x86_64（换镜像/交叉编译/使用 Rosetta）
换行/权限：CRLF→LF；chmod +x scripts/*
时区/Locale：容器加 TZ 和 LANG 环境变量

一份可直接套用的 Makefile（示意）

.PHONY: setup dev test lint build run clean smoke
setup:
\t./scripts/system_bootstrap.sh && ./scripts/install_deps.sh
dev:
\t./scripts/dev.sh
test:
\t./scripts/test.sh
lint:
\t./scripts/lint.sh
build:
\t./scripts/build.sh
run:
\t./scripts/run.sh
smoke:
\t./scripts/smoke.sh
clean:
\trm -rf .venv node_modules build dist

给你的 AI 提问合集（按阶段复用）

“为 X 项目生成 .env.example + 解释每个变量用途与默认值建议。”
“把下面报错栈分析成可能的 3 个根因，按排查顺序给命令与预期输出。”
“基于这段 Dockerfile，优化构建缓存命中率并减镜像体积。”
“生成 GitHub Actions workflow：缓存依赖、构建、测试、构建镜像、推送到私有仓库并生成 SBOM。”

如果你愿意，我也可以按你正在做的具体项目/语言，直接产出一套可运行的：Dockerfile、docker-compose.yml、.env.example、Makefile、README 快速开始。只要把仓库结构或核心依赖贴上来即可。

下面给你一份C 语言开发环境搭建从 0 到可运行的速成到专业版指南（Windows / macOS / Linux 通吃），包含安装命令、脚手架、构建、调试、依赖管理与质量保障。照着做就能把任意 C 项目跑起来并做到可复现、可交接。

一、最快路线（10 分钟上手）

工具链 + IDE + 构建系统 = gcc/clang + VS Code + CMake/Make

1) 安装编译器与常用工具

Windows（两选一）

MSVC（官方）
安装 Visual Studio 2022 勾选 “使用 C++ 的桌面开发”，或安装 Build Tools。
打开 Developer PowerShell for VS：
1
cl /?
MinGW-w64（类 GCC 体验，推荐经 MSYS2）
1. 安装 MSYS2，打开 MSYS2 UCRT64 终端
2. 执行：
1
2
pacman -S --needed base-devel mingw-w64-ucrt-x86_64-toolchain cmake ninja git
gcc --version && cmake --version
之后使用 MSYS2 UCRT64 或将 C:\msys64\ucrt64\bin 加入 PATH。

macOS

1
2
3

xcode-select --install            # 安装 clang/lldb
brew install cmake ninja pkg-config
clang --version && cmake --version

调试器建议用 lldb（随 Xcode 提供）。gdb 在 macOS 需签名，较繁琐。

Ubuntu / Debian

1
2
3

sudo apt update
sudo apt install -y build-essential gcc gdb cmake ninja-build pkg-config valgrind
gcc --version && cmake --version

2) VS Code 基础（可选但强烈推荐）

安装扩展：C/C++（ms-vscode.cpptools）、CMake Tools、CodeLLDB（macOS）或 C/C++ Extension Pack。
打开项目后 ⌘/Ctrl+Shift+P → CMake: Configure 自动生成构建目录。

二、最小可运行项目脚手架

c-hello/
├─ src/
│  └─ main.c
├─ include/
│  └─ hello.h
├─ CMakeLists.txt
├─ Makefile                # 可选：喜欢用 make 时
├─ .clang-format           # 可选：统一代码风格
└─ .vscode/launch.json     # 可选：一键断点调试

`src/main.c`

#include <stdio.h>
#include "hello.h"

int main(void) {
    printf("sum(2, 40) = %d\n", sum(2, 40));
    return 0;
}

`include/hello.h`

#ifndef HELLO_H
#define HELLO_H
int sum(int a, int b);
#endif

`src/hello.c`（别忘了）

1	int sum(int a, int b) { return a + b; }

选项 A：CMake（跨平台首选）

`CMakeLists.txt`

cmake_minimum_required(VERSION 3.20)
project(c_hello C)
set(CMAKE_C_STANDARD 11)
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

add_executable(c_hello
  src/main.c
  src/hello.c
)
target_include_directories(c_hello PRIVATE include)

# 打开 AddressSanitizer：内存越界/Use-After-Free 快速发现
option(ENABLE_ASAN "Enable AddressSanitizer" ON)
if (ENABLE_ASAN AND (CMAKE_C_COMPILER_ID MATCHES "GNU|Clang"))
  target_compile_options(c_hello PRIVATE -fsanitize=address -fno-omit-frame-pointer -g -O0 -Wall -Wextra -Werror)
  target_link_options(c_hello PRIVATE -fsanitize=address)
elseif (MSVC)
  target_compile_options(c_hello PRIVATE /W4 /WX /Zi /Od)
endif()

include(CTest)
if (BUILD_TESTING)
  add_executable(test_sum tests/test_sum.c src/hello.c)
  target_include_directories(test_sum PRIVATE include)
  add_test(NAME test_sum COMMAND test_sum)
endif()

构建与运行（Ninja 或 Make 都可）：

1
2
3

cmake -S . -B build -G "Ninja"
cmake --build build
./build/c_hello        # Windows: .\build\c_hello.exe

选项 B：Make（最小依赖）

`Makefile`

CC ?= gcc
CFLAGS ?= -std=c11 -Wall -Wextra -Werror -O0 -g
INCLUDE := -Iinclude
SRC := src/main.c src/hello.c
BIN := build
OUT := $(BIN)/c_hello

$(BIN)/%:
	@mkdir -p $(BIN)

all: $(BIN)/c_hello
$(BIN)/c_hello: | $(BIN)
	$(CC) $(CFLAGS) $(INCLUDE) $(SRC) -o $(OUT)

run: all
	./$(OUT)

clean:
	rm -rf $(BIN)
.PHONY: all run clean

三、调试（CLI 与 VS Code）

CLI 调试

GDB（Linux/MinGW）：gdb ./build/c_hello → break main → run → bt → p a
LLDB（macOS）：lldb ./build/c_hello → b main → r → bt → p a
MSVC（Windows/CL）：在 Developer Command Prompt 用 devenv/VS 图形界面或 VS Code 配置 cppvsdbg。

VS Code 启动配置示例：`.vscode/launch.json`

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug (gdb/lldb)",
      "type": "cppdbg",
      "request": "launch",
      "program": "${workspaceFolder}/build/c_hello",
      "args": [],
      "cwd": "${workspaceFolder}",
      "MIMode": "${env:OS} == 'Windows_NT' ? 'gdb' : 'lldb'",
      "stopAtEntry": false,
      "externalConsole": false
    }
  ]
}

四、单元测试（最小可用）

不引入第三方框架也能测：用 assert 写一个可执行测试，配合 CTest 统一跑。

tests/test_sum.c

#include <assert.h>
#include "hello.h"

int main(void) {
    assert(sum(2, 40) == 42);
    return 0;
}

运行：

1
2
3

cmake -S . -B build -DBUILD_TESTING=ON
cmake --build build
ctest --test-dir build --output-on-failure

需要更完备的断言/报告可选：Unity, cmocka, Criterion（配合 vcpkg/Conan 安装即可，见下）。

五、第三方依赖管理（两条成熟路线）

1) vcpkg（微软维护，CMake 结合顺滑）

安装 vcpkg 后，配置：

1 2	cmake -S . -B build -G "Ninja" \ -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake

在 vcpkg.json 写依赖（例：cjson）：

1	{ "name": "c-hello", "version-string": "0.1.0", "dependencies": ["cjson"] }

在 CMakeLists.txt 使用：

1 2	find_package(cJSON CONFIG REQUIRED) target_link_libraries(c_hello PRIVATE cjson)

2) Conan（通用包管）

conanfile.txt

[requires]
cjson/1.7.18

[generators]
CMakeDeps
CMakeToolchain

安装并集成：

conan profile detect
conan install . --output-folder=build --build=missing
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake
cmake --build build

六、质量与性能（上线前该做的事）

代码风格与静态检查

clang-format（放根目录 .clang-format）：

1
2
3

BasedOnStyle: LLVM
IndentWidth: 4
ColumnLimit: 100

clang-tidy（.clang-tidy）：

1 2	Checks: '-,clang-analyzer-,bugprone-,performance-,readability-' WarningsAsErrors: ''

cppcheck：cppcheck --enable=all --inconclusive --std=c11 src

内存/数据竞争排查

AddressSanitizer：GCC/Clang 加 -fsanitize=address -fno-omit-frame-pointer -O0 -g
UndefinedBehaviorSanitizer：-fsanitize=undefined
ThreadSanitizer（多线程）：-fsanitize=thread（不与 ASan 同时）
Valgrind（Linux）：valgrind --leak-check=full ./build/c_hello

性能初步

gprof：-pg 编译 → gprof ./build/c_hello gmon.out
perf（Linux）：perf record ./build/c_hello && perf report

七、容器/Dev Container（团队同构、可复现）

`Dockerfile`（最小开发镜像）

FROM debian:stable-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential gcc gdb cmake ninja-build git pkg-config \
 && rm -rf /var/lib/apt/lists/*
WORKDIR /work

`.devcontainer/devcontainer.json`

{
  "name": "C Dev",
  "build": { "dockerfile": "Dockerfile" },
  "features": { "ghcr.io/devcontainers/features/common-utils:2": {} },
  "customizations": {
    "vscode": {
      "extensions": ["ms-vscode.cpptools", "ms-vscode.cmake-tools"]
    }
  }
}

八、常见坑与对策

标准版本不一致：明确 -std=c11（GCC/Clang）或在 MSVC 侧开启 C17 支持（新编译器默认 OK）。
Windows 安全函数警告：strcpy 等触发 _CRT_SECURE_NO_WARNINGS；更推荐用 strncpy_s 等。
行尾/编码：统一 LF 与 UTF-8（.editorconfig）。
32/64 位 & 平台 ABI：vcpkg/Conan 选择正确 triplet/profile（如 x64-windows）。
路径含空格：CMake/Make 中注意引号包裹变量。
macOS gdb 不易用：优先 lldb。
MinGW 与 MSVC 混链：避免混用不同工具链产物（库/对象文件不兼容）。

你可以怎么用这份指南

直接复制脚手架文件到你的仓库。
先用 CMake 方案本地构建；跑通后再决定是否接入 vcpkg/Conan。
打开 Sanitizer + clang-tidy，把问题在开发期解决掉。
如需，我也可以基于你的项目结构生成一份可运行的 starter（CMake + vcpkg/Conan + VS Code 配置），把文件都填好。只要把你的目录树或关键依赖贴过来即可。

下面给你一份Java 开发环境从 0 到可运行的速成到专业版指南，覆盖安装、版本管理、项目脚手架、构建/测试/调试、质量与 CI、容器与可复现交付。照着做，任意 Java 项目都能稳稳跑起来并便于交接。

1) 安装 JDK（首选 LTS：21）

推荐发行版：Eclipse Temurin（OpenJDK 社区版，稳定、免费）
验证安装：java -version、javac -version

Windows
- winget：winget install EclipseAdoptium.Temurin.21.JDK
- choco：choco install temurin21 -y
- Scoop：scoop bucket add java && scoop install temurin-lts
macOS
- Homebrew（cask）：brew install --cask temurin@21
- 链接（如需）：sudo ln -sfn $(/usr/libexec/java_home -v 21) /Library/Java/JavaVirtualMachines/current
Linux
- Debian/Ubuntu：sudo apt install -y openjdk-21-jdk
- Fedora/RHEL：sudo dnf install -y java-21-openjdk-devel
- Arch：sudo pacman -S jdk21-openjdk

设置 JAVA_HOME（示例）

Windows PowerShell：$env:JAVA_HOME="C:\Program Files\Eclipse Adoptium\jdk-21" 并加入 PATH
macOS/Linux：export JAVA_HOME=$(/usr/libexec/java_home -v 21 || dirname $(dirname $(readlink -f $(which java))))

2) 多版本切换（建议：开发机装）

macOS/Linux → SDKMAN!
安装：curl -s "https://get.sdkman.io" | bash
列表/安装/切换：sdk list java → sdk install java 21-tem → sdk use java 21-tem
Windows/跨平台 → jabba
安装：curl -sL https://github.com/shyiko/jabba/raw/master/install.sh | bash
jabba ls-remote → jabba install temurin@21 → jabba use temurin@21

原则：本地/CI/容器尽量同一大版本（如 21 LTS）。

3) 构建工具与 IDE

构建：Gradle（现代、快）、Maven（生态广）
IDE：IntelliJ IDEA（首选）、VS Code（配 Java 扩展包）、Eclipse（备选）
验证工具链：gradle -v 或 mvn -v（也可只用 wrapper，不必全局安装）

4) 最小可运行项目脚手架（两选一）

4.1 Gradle（推荐，Kotlin DSL）

mkdir java-hello && cd java-hello
gradle init --type java-application --dsl kotlin --test-framework junit-jupiter \
  --project-name java-hello --package com.example
./gradlew run     # 首次会自动下载 Gradle
./gradlew test

build.gradle.kts 关键点

plugins {
  application
  jacoco
  id("com.diffplug.spotless") version "7.0.0.BETA2" // 代码格式化
}
java { toolchain { languageVersion.set(JavaLanguageVersion.of(21)) } }
application { mainClass.set("com.example.App") }

tasks.test { useJUnitPlatform() }
spotless { java { googleJavaFormat() } }   // 统一风格

4.2 Maven（经典稳健）

mvn -q archetype:generate \
  -DgroupId=com.example -DartifactId=java-hello \
  -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
cd java-hello
./mvnw -q -DskipTests package
./mvnw -q test

pom.xml 关键点（Java 21 + JUnit5 + Spotless）

<properties>
  <maven.compiler.source>21</maven.compiler.source>
  <maven.compiler.target>21</maven.compiler.target>
</properties>
<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-surefire-plugin</artifactId>
      <version>3.2.5</version>
    </plugin>
    <plugin>
      <groupId>jacoco</groupId>
      <artifactId>jacoco-maven-plugin</artifactId>
      <version>0.8.12</version>
      <executions>
        <execution><goals><goal>prepare-agent</goal></goals></execution>
        <execution><id>report</id><phase>test</phase><goals><goal>report</goal></goals></execution>
      </executions>
    </plugin>
  </plugins>
</build>
<dependencies>
  <dependency>
    <groupId>org.junit.jupiter</groupId><artifactId>junit-jupiter</artifactId><version>5.10.2</version><scope>test</scope>
  </dependency>
</dependencies>

5) 运行、测试、调试

本地运行

Gradle：./gradlew run
Maven（带 exec 插件时）：./mvnw exec:java -Dexec.mainClass=com.example.App

单元测试（JUnit 5）

Gradle：./gradlew test
Maven：./mvnw test

断点调试（本地）

IDEA/VS Code 直接点“Debug”即可；Gradle/Maven 需生成可执行配置或添加 IDE 插件。

远程调试（端口 5005）

在 JVM 启动参数里加：

1	-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005

IDE 选择 “Attach to 5005” 即可。

6) 配置与环境

系统属性：-Dkey=value（如 -Dfile.encoding=UTF-8 -Duser.timezone=Asia/Shanghai）
环境变量：System.getenv("KEY") 获取；12-Factor 风格推荐以 env 管理密钥
不同环境：Gradle/Maven profile 或 Spring/Quarkus 等框架的 profile 区分

7) 质量与安全

静态分析：SpotBugs、Checkstyle、PMD（Gradle/Maven 插件即可）
格式化：Spotless + Google Java Format（见 Gradle 配置）
代码覆盖：JaCoCo（Gradle：./gradlew jacocoTestReport；Maven 见上）
依赖漏洞扫描：OWASP Dependency-Check / Gradle Versions Plugin / Maven Versions Plugin

8) 性能与可观测

JFR（Flight Recorder）：-XX:StartFlightRecording=filename=app.jfr,dumponexit=true
JMC（Mission Control）：分析 JFR
内存与 GC：常见参数
-Xms512m -Xmx512m -XX:+UseG1GC -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=./
OpenTelemetry Java Agent（零侵入）：
-javaagent:opentelemetry-javaagent.jar -Dotel.service.name=myapp

9) 容器与 Dev Container（可复现首选）

多阶段 Dockerfile（Gradle 例）

# 构建镜像
FROM eclipse-temurin:21-jdk AS build
WORKDIR /app
COPY . .
RUN ./gradlew --no-daemon clean build -x test

# 运行镜像（JRE 即可）
FROM eclipse-temurin:21-jre
WORKDIR /app
COPY --from=build /app/build/libs/*-all.jar app.jar
ENV JAVA_TOOL_OPTIONS="-XX:+UseContainerSupport -XX:MaxRAMPercentage=75"
EXPOSE 8080
ENTRYPOINT ["java","-jar","/app/app.jar"]

若不是 fat-jar（shadowJar），复制实际产物路径；或用 Spring Boot 的 bootJar。

.devcontainer/devcontainer.json

{
  "name": "Java Dev",
  "image": "mcr.microsoft.com/devcontainers/java:1-21-bookworm",
  "customizations": { "vscode": { "extensions": ["vscjava.vscode-java-pack", "richardwillis.vscode-spotless-gradle"] } }
}

10) CI（GitHub Actions 示例）

name: ci
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '21'
          cache: 'gradle'   # maven 换成 'maven'
      - run: ./gradlew --no-daemon build

11) 常见坑 & 快速排查

JDK vs JRE：开发/编译需要 JDK（含 javac），运行可用 JRE。容器/生产建议 JRE/缩减运行时（jlink）。
编码/时区：跨平台统一 -Dfile.encoding=UTF-8 -Duser.timezone=UTC/Asia/Shanghai。
证书/代理：公司代理/私有 CA 导致 HTTPS 报错；将 CA 导入 JVM truststore 或使用系统 truststore。
端口占用：lsof -i :8080（或 netstat/Get-NetTCPConnection）定位。
内存不足/容器：启用容器自适应：-XX:+UseContainerSupport -XX:MaxRAMPercentage=…
模块化（JPMS）冲突：显式声明 module-info.java 或保持类路径模式（classpath）避免误碰模块边界。
Gradle 守护进程过多：./gradlew --stop 清理。

12) 10 步极简 Checklist

安装 Temurin JDK 21，设好 JAVA_HOME
安装 Gradle/Maven（或只用 wrapper）
gradle init / mvn archetype:generate 创建骨架
设定 Java Toolchain/Compiler 为 21
./gradlew run / ./mvnw test 验证可运行
加上 JUnit5 + JaCoCo + Spotless
配置 远程调试（5005）与启动脚本
写 README 的“10 步快速开始”
加 Dockerfile 与 Dev Container（同构环境）
接入 CI（setup-java + 缓存），保持与本地一致

如果你给我项目框架（如 Spring Boot / Micronaut / Quarkus）或仓库结构，我可以直接产出对应的 build.gradle.kts/pom.xml、Dockerfile、.devcontainer、README 快速开始、launch.json 一套可跑模板，帮你马上落地。

给你一份Python 语言环境从 0 到可复现可交接的实战指南（Windows / macOS / Linux 通吃）。按它走，能把任何 Python 项目在本机、容器、CI 上稳稳跑起来。

1) 装运行时 & 版本管理（首选 3.11/3.12）

三条成熟路线（任选一条即可）：

uv 一把梭（快：装解释器、管虚拟环境、装依赖、跑脚本）
安装：curl -LsSf https://astral.sh/uv/install.sh | sh（Win 用 PowerShell 安装器）
pyenv / asdf（多版本切换稳定；跨项目一致）
macOS/Linux：brew install pyenv 或 asdf plugin add python
Windows：choco install pyenv-win（或用 asdf for Windows）
Conda（Miniforge/Mambaforge）（数据科学多，带原生库更省心）
安装 Miniforge 后用 mamba 管理环境与包。

C 扩展必备编译工具：
macOS：xcode-select --install；Ubuntu：sudo apt install -y build-essential python3-dev；
Windows：安装 Visual Studio Build Tools（含 “使用 C++ 的桌面开发”）。

2) 项目骨架（src 布局 + pyproject 一步到位）

myproj/
├─ pyproject.toml
├─ src/myproj/__init__.py
├─ src/myproj/__main__.py
├─ tests/test_basic.py
└─ README.md

极简 pyproject.toml（uv/poetry/hatch 通用）

[project]
name = "myproj"
version = "0.1.0"
description = "My awesome app"
readme = "README.md"
requires-python = ">=3.11"
dependencies = []

[tool.ruff]                # Lint + isort 合一
line-length = 100
target-version = "py311"

[tool.black]
line-length = 100
target-version = ["py311"]

[tool.pytest.ini_options]
addopts = "-q"
testpaths = ["tests"]

3) 虚拟环境与依赖（3 种做法，三选一）

A. uv（推荐，速度快、零脑负担）

# 新建并激活虚拟环境
uv venv           # 生成 .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 安装依赖（写到 pyproject）
uv add requests pytest
# 锁定 & 安装（prod）
uv sync --frozen

运行脚本/模块：uv run python -m myproj

B. Poetry（发行版/库友好）

pipx install poetry
poetry env use 3.12
poetry add requests
poetry add -D pytest ruff black
poetry install --no-root
poetry run python -m myproj

C. pip + venv + pip-tools（经典、透明）

python -m venv .venv && source .venv/bin/activate
python -m pip install --upgrade pip pip-tools
echo "requests==2.*" > requirements.in
pip-compile requirements.in    # 生成 requirements.txt（锁版本）
pip install -r requirements.txt

全局 CLI 建议用 pipx：pipx install pre-commit ruff

4) 统一命令入口（Makefile / justfile / hatch task）

示例 Makefile

.PHONY: dev test lint fmt type clean
dev:          ## 本地开发启动
\tuv run python -m myproj
test:         ## 单测
\tuv run pytest
lint:         ## 静态检查
\tuv run ruff check .
fmt:          ## 自动格式化
\tuv run ruff format .
type:         ## 类型检查
\tuv run mypy src
clean:
\trm -rf .venv .pytest_cache .ruff_cache .mypy_cache dist build

5) 质量基线（ruff/black/mypy + pre-commit）

1
2
3

uv add -D ruff mypy black pre-commit
pre-commit sample-config > .pre-commit-config.yaml
pre-commit install

更实用的 .pre-commit-config.yaml

repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
  rev: v0.6.0
  hooks:
  - id: ruff
  - id: ruff-format
- repo: https://github.com/psf/black
  rev: 24.8.0
  hooks:
  - id: black
- repo: https://github.com/pre-commit/mirrors-mypy
  rev: v1.10.0
  hooks:
  - id: mypy
    additional_dependencies: []

6) 测试与覆盖率

1 2	uv add -D pytest pytest-cov uv run pytest --cov=src --cov-report=term-missing

最小单测 tests/test_basic.py

1 2	def test_truth(): assert 21 * 2 == 42

7) 私有源 / 代理 / 镜像

临时：PIP_INDEX_URL=https://<your-index>/simple uv pip install ...
持久化：pip.conf / pip.ini
Linux/macOS: ~/.config/pip/pip.conf；Windows: %APPDATA%\pip\pip.ini

1
2
3

[global]
index-url = https://<your-index>/simple
trusted-host = <your-index>

企业代理：HTTPS_PROXY=http://user:pass@proxy:port（安装与运行都可用）

8) Jupyter / 数据科学要点

1
2
3

uv add -D notebook ipykernel
uv run python -m ipykernel install --user --name myproj
# VS Code/Notebook 选择 "myproj" 内核即可

科学栈原生库多：优先 Conda/Miniforge 或用预编译轮子（manylinux/Apple Silicon）。

9) 容器与 Dev Container（环境同构）

精简 Dockerfile（基于 Debian/uv）

FROM python:3.12-slim
# 可选：换源与构建依赖
RUN apt-get update && apt-get install -y --no-install-recommends build-essential && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY pyproject.toml ./
# 使用 uv（也可直接 pip）
RUN pip install --no-cache-dir uv && uv sync --no-editable --frozen || true

COPY . .
RUN uv sync --frozen
CMD ["uv", "run", "python", "-m", "myproj"]

.devcontainer/devcontainer.json

{
  "name": "Python Dev",
  "image": "mcr.microsoft.com/devcontainers/python:3.12",
  "features": { "ghcr.io/devcontainers/features/common-utils:2": {} },
  "customizations": { "vscode": { "extensions": ["ms-python.python", "ms-toolsai.jupyter", "charliermarsh.ruff"] } }
}

10) CI（GitHub Actions）

name: ci
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-python@v5
      with: { python-version: '3.12' }
    - uses: astral-sh/setup-uv@v3
    - run: uv sync --frozen
    - run: uv run pytest --cov=src

11) 常见坑 & 快速排查

“Externally Managed Environment” 报错：在系统 Python 上装包受限。请用 .venv/uv venv/Conda。
Apple Silicon：优先用 arm64 解释器与轮子；缺轮子时需装编译链/开 Rosetta（不推荐）。
Windows 原生扩展：缺编译器→装 Build Tools；或找预编译轮子。
时区/编码：统一 TZ=Asia/Shanghai、PYTHONIOENCODING=UTF-8。
慢安装：开缓存；优先 uv；使用企业镜像；锁定版本避免反复求解。
多项目混乱：每仓库一套 .venv + pyproject.toml + pre-commit。

12) “10 步极简 Checklist”

安装 uv（或 pyenv/Conda）
uv venv & 激活
写好 pyproject.toml（含 requires-python）
uv add 安装依赖（或 poetry add / pip-compile）
uv run python -m myproj 跑通
上 pytest + 覆盖率
上 ruff/black/mypy + pre-commit install
写 Makefile 统一命令
准备 Dockerfile / Dev Container
接入 GitHub Actions 并锁版本

需要的话，把你的**仓库结构 / 使用场景（脚本、Web、数据科学）**贴上来，我直接给你生成：pyproject.toml、Makefile、pre-commit、Dockerfile、devcontainer、CI 一整套可跑模板。

给你一份JavaScript（含 TypeScript）开发环境从 0 到可复现的实战清单。覆盖：Node 版本管理、包管理器、脚手架、质量基线、调试、容器与 CI。照着做，前后端项目都能稳稳跑起来。

1) 装 Node.js（推荐 LTS：22.x）

三种靠谱方案（选一即可）：

nvm/fnm（常用）
macOS/Linux：

# nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install --lts
nvm use --lts
node -v && npm -v

或更快的 fnm：brew install fnm && fnm install --lts && fnm use --lts

Windows（nvm-windows 或 scoop/winget）
装 nvm-windows 后：
1
2
3
nvm install lts
nvm use lts
node -v

asdf（跨语言统一）

1
2
3

asdf plugin add nodejs
asdf install nodejs 22.#
asdf global nodejs 22.#

建议：项目根目录放一个 .nvmrc 写上 22，团队一条命令 nvm use 即统一版本。

2) 包管理器与新项目

启用 Corepack（Node 自带的包管桥）并选 pnpm（速度与仓库管理更好）：

1
2
3

corepack enable
corepack prepare pnpm@latest --activate
pnpm -v

A. Node 应用（TypeScript 模板，推荐）

mkdir js-app && cd js-app
pnpm init
pnpm add -D typescript tsx @types/node
pnpm add -D eslint @eslint/js typescript-eslint prettier
pnpm add -D vitest @vitest/coverage-v8
pnpm add -D nodemon

目录结构

js-app/
├─ src/
│  └─ index.ts
├─ test/
│  └─ basic.test.ts
├─ tsconfig.json
├─ package.json
├─ .eslintrc.cjs
├─ .prettierrc
└─ .gitignore

src/index.ts

1 2	export function sum(a: number, b: number) { return a + b; } if (import.meta.main) console.log(sum(2, 40));

test/basic.test.ts

1
2
3

import { describe, it, expect } from "vitest";
import { sum } from "../src/index";
describe("sum", () => { it("42", () => expect(sum(2,40)).toBe(42)); });

tsconfig.json（最小可用）

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "esModuleInterop": true,
    "types": ["node"],
    "outDir": "dist"
  },
  "include": ["src", "test"]
}

package.json 关键段

{
  "type": "module",
  "engines": { "node": ">=22" },
  "packageManager": "pnpm@9",
  "scripts": {
    "dev": "nodemon -e ts --exec \"tsx src/index.ts\"",
    "build": "tsc -p tsconfig.json",
    "start": "node dist/index.js",
    "test": "vitest run",
    "test:watch": "vitest",
    "lint": "eslint .",
    "fmt": "prettier -w ."
  }
}

.eslintrc.cjs

// eslint.config.js 风格也可，这里用传统配置文件便于理解
module.exports = [
  { ignores: ["dist", "node_modules"] },
  {
    files: ["**/*.{ts,tsx,js}"],
    languageOptions: { parserOptions: { ecmaVersion: "latest", sourceType: "module" } },
    plugins: { "@typescript-eslint": require("typescript-eslint") },
    rules: { "no-unused-vars": "warn" }
  }
];

.prettierrc

1	{ "singleQuote": true, "semi": true, "printWidth": 100 }

B. 前端工程（Vite + React/Vue/…）

pnpm create vite@latest web-app -- --template react-ts
cd web-app
pnpm i
pnpm dev          # http://localhost:5173
pnpm build && pnpm preview

3) 环境变量与配置

用 dotenv 管理本地环境：pnpm add dotenv，在入口加载 import 'dotenv/config'。
约定：提交 .env.example，本地用 .env，CI 用平台 Secret。
前端（Vite）暴露变量需以 VITE_ 开头。

4) 调试与 IDE

Node 调试：node --inspect-brk dist/index.js 然后在 VS Code Attach 到 9229。
VS Code 推荐扩展：ESLint、Prettier、TypeScript ESLint、Vitest、Playwright（端到端）。

.vscode/launch.json（Node attach 示例）

{
  "version": "0.2.0",
  "configurations": [
    { "type": "node", "request": "attach", "name": "Attach 9229", "port": 9229 }
  ]
}

5) 提交前质量基线（可选但强烈建议）

1 2	pnpm add -D husky lint-staged pnpm dlx husky init

.husky/pre-commit

1 2	#!/usr/bin/env sh pnpm lint-staged

package.json 补充

1	{ "lint-staged": { "*.{js,ts,tsx,css,md}": ["eslint --fix", "prettier -w"] } }

6) Docker 与 Dev Container（同构环境）

Dockerfile（Node 22 + pnpm，缓存友好）

FROM node:22-alpine AS base
WORKDIR /app
RUN corepack enable && corepack prepare pnpm@9 --activate

FROM base AS deps
COPY pnpm-lock.yaml ./
RUN pnpm fetch

FROM base AS build
COPY --from=deps /root/.local/share/pnpm/store /root/.local/share/pnpm/store
COPY package.json tsconfig.json ./
COPY src ./src
RUN pnpm install --offline --frozen-lockfile \
 && pnpm build

FROM node:22-alpine AS run
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/dist ./dist
COPY package.json ./
CMD ["node", "dist/index.js"]

.devcontainer/devcontainer.json

{
  "name": "JS Dev",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:22",
  "features": { "ghcr.io/devcontainers/features/common-utils:2": {} },
  "customizations": { "vscode": { "extensions": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"] } }
}

7) CI（GitHub Actions，pnpm 缓存）

name: ci
on: [push, pull_request]
jobs:
  node:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'pnpm'
      - run: corepack enable && corepack prepare pnpm@9 --activate
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm test
      - run: pnpm build

8) 常见坑 & 快速排查

Node 版本不一致 → 用 .nvmrc / engines + CI 固定 22；容器同版本。
依赖解析慢/反复不一致 → 固定 lockfile，CI 用 --frozen-lockfile；Docker 用 pnpm fetch 提前拉缓存。
ESM/CJS 混用 → package.json 指定 "type": "module"；旧库需要 createRequire 或转到 commonjs 构建。
Windows 路径/权限 → 用 git config core.autocrlf input；脚本中避免 rm 等用 rimraf。

公司代理/私有源 → 配置 ~/.npmrc：

1 2	registry=https://your-registry/ strict-ssl=false # 如需信任公司 CA

9) “10 步极简 Checklist”

安装并切到 Node 22 LTS（nvm/fnm/asdf）
corepack enable，准备 pnpm
初始化项目（Node+TS 或 Vite 前端）
写 tsconfig.json，"type":"module"
加脚本：dev / build / start / test / lint / fmt
装 ESLint + Prettier + Vitest 并跑通单测
.env.example 与 dotenv 管理配置
加 husky + lint-staged（提交即检查）
准备 Dockerfile 与 Dev Container
接入 GitHub Actions（setup-node + pnpm 缓存）

如果你贴出项目类型（前端/Node 服务/Monorepo 等）和目录结构，我可以直接把 package.json / tsconfig / ESLint/Prettier / Dockerfile / CI 一整套可跑模板按你的场景定制好。

给你一份Kotlin（JVM / Multiplatform / Android）环境从 0 到可复现的实战清单。照着做，任意 Kotlin 项目都能稳稳跑起来并便于交接。

1) 基础安装（JDK + Kotlin/IDE）

首选 JDK 21 LTS（Temurin），IDE 用 IntelliJ IDEA（Kotlin/JVM 足够；做 Android 用 Android Studio）。

macOS

1
2
3

brew install --cask temurin@21
brew install gradle kotlin   # 可选：装 CLI；常用用 Gradle Wrapper 即可
java -version && kotlinc -version

Ubuntu/Debian

1
2
3

sudo apt update && sudo apt install -y openjdk-21-jdk
curl -s "https://get.sdkman.io" | bash && source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk install kotlin  # 可选

Windows
用 winget/choco 装 Temurin 21；IDEA/Android Studio 用官方安装器。
1
winget install EclipseAdoptium.Temurin.21.JDK

多版本切换建议 SDKMAN!（macOS/Linux） 或 jabba。Android 端请用 Android Studio 管理 SDK/NDK/构建工具。

2) 最小可运行（Kotlin/JVM 应用）

用 Gradle（Kotlin DSL）生成骨架：

mkdir kotlin-hello && cd kotlin-hello
gradle init --type kotlin-application --dsl kotlin \
  --project-name kotlin-hello --package com.example
./gradlew run
./gradlew test

关键文件示例

settings.gradle.kts

1	rootProject.name = "kotlin-hello"

build.gradle.kts

plugins {
  kotlin("jvm") version "2.0.0"   // 用当前稳定版或团队约定版本
  application
  jacoco
  id("com.diffplug.spotless") version "6.25.0" // 统一格式
  id("io.gitlab.arturbosch.detekt") version "1.23.6" // 静态检查
}

repositories { mavenCentral() }

kotlin { jvmToolchain(21) }       // 与 JDK 对齐
application { mainClass.set("com.example.AppKt") }

dependencies {
  testImplementation(kotlin("test"))          // Kotlin Test (JUnit5 平台)
  // implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.1") // 需要协程再开
}

tasks.test { useJUnitPlatform() }
spotless {
  kotlin { ktlint() }
  kotlinGradle { ktlint() }
}
detekt { buildUponDefaultConfig = true }

src/main/kotlin/com/example/App.kt

1 2	package com.example fun main() = println("Hello Kotlin ${2 + 40}")

3) Kotlin Multiplatform（KMP）骨架（JVM + JS）

需要多端复用时再用 KMP，先从 JVM 跑通再加目标。

build.gradle.kts

plugins {
  kotlin("multiplatform") version "2.0.0"
  id("org.jetbrains.kotlin.plugin.serialization") version "2.0.0"
}

kotlin {
  jvm { jvmToolchain(21) }
  js(IR) { browser(); nodejs() }
  // 如需原生：linuxX64(), mingwX64(), macosArm64() 等（对应平台装好工具链）
  sourceSets {
    val commonMain by getting {
      dependencies {
        implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3")
        // implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.1")
      }
    }
    val commonTest by getting { dependencies { implementation(kotlin("test")) } }
  }
}
repositories { mavenCentral() }

命令：./gradlew jvmTest jsBrowserDevelopmentRun（或 jsNodeTest）

Kotlin/Native 前置：macOS 需 Xcode；Windows 需 MSVC；Linux 需 Clang/LLD。首次构建会自动拉目标工具链。

4) Android（最短路径）

装 Android Studio，新建 Empty Views Activity 或 Compose 模板。

build.gradle.kts 里使用：

1 2	plugins { id("com.android.application") version "8.5.0" apply false kotlin("android") version "2.0.0" apply false }

App 模块启用：

1 2	android { namespace = "com.example.app"; compileSdk = 34; defaultConfig { minSdk = 24 } } kotlin { jvmToolchain(21) }

Android 优先用 Gradle Wrapper + Android Gradle Plugin 指定版本；SDK/NDK 在 SDK Manager 配齐即可。

5) 本地调试与远程调试

IDE 断点：IDEA/Android Studio 一键 Debug。
JVM 远程调试（5005）：运行时加
1
-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
VS Code/IDEA 选择 Attach to 5005。

6) 提交前质量基线

# 统一格式 / 静态检查 / 覆盖率
./gradlew spotlessApply
./gradlew detekt
./gradlew test jacocoTestReport

可选：ktlint 原生插件（替代 Spotless）

1	plugins { id("org.jlleitschuh.gradle.ktlint") version "12.1.0" }

7) 依赖与版本管理

统一写法：libs.versions.toml（Gradle Version Catalog）

[versions]
kotlin = "2.0.0"
junit = "5.10.2"

[libraries]
junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }

保持 JDK=21、Kotlin 编译器版本、AGP 版本 在本地/CI/容器一致。

8) 容器与 Dev Container（可复现）

Dockerfile（JVM 应用示例）

FROM eclipse-temurin:21-jdk AS build
WORKDIR /app
COPY . .
# 使用仓库自带 Gradle Wrapper；首次会下载 Gradle
RUN ./gradlew --no-daemon clean build -x test

FROM eclipse-temurin:21-jre
WORKDIR /app
COPY --from=build /app/build/libs/*.jar app.jar
ENV JAVA_TOOL_OPTIONS="-XX:+UseContainerSupport -XX:MaxRAMPercentage=75"
EXPOSE 8080
ENTRYPOINT ["java","-jar","/app/app.jar"]

.devcontainer/devcontainer.json

{
  "name": "Kotlin Dev",
  "image": "mcr.microsoft.com/devcontainers/java:1-21-bookworm",
  "customizations": { "vscode": { "extensions": ["fwcd.kotlin", "vadimcn.vscode-lldb"] } }
}

9) CI（GitHub Actions）

name: ci
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '21'
          cache: gradle
      - run: ./gradlew --no-daemon build

10) 常见坑 & 快速排查

JDK 不匹配：编译/运行尽量都用 JDK 21；Gradle jvmToolchain(21) 强制统一。
Kotlin 版本与 Gradle/AGP 兼容：三者需成对；版本不兼容时升级 plugin 或降级编译器。
Windows 路径/换行：git config core.autocrlf input；Gradle 脚本尽量用跨平台命令。
KMP 原生目标构建失败：检查平台工具链（Xcode/Clang/LLD）与 SDK；先关掉不需要的 target。
依赖地狱：用 Version Catalog 与锁定（gradle/dependency-locking），CI --no-refresh-dependencies。

性能慢：gradle.properties 开启缓存/并行：

org.gradle.parallel=true
org.gradle.caching=true
org.gradle.jvmargs=-Xmx2g -Dfile.encoding=UTF-8
kotlin.code.style=official

11) “10 步极简 Checklist”

安装 JDK 21 + IDEA/Android Studio
用 Gradle init 生成 Kotlin/JVM 骨架并 ./gradlew run
kotlin("jvm") + jvmToolchain(21) 固定版本
加 Spotless/ktlint + detekt，统一风格与静态检查
配置 JUnit5/Kotlin Test，./gradlew test
写 Version Catalog，统一依赖版本
若多端，改成 KMP 并逐步启用 target
加 Dockerfile 与 Dev Container
接入 GitHub Actions（setup-java + Gradle 缓存）
写好 README 的“快速开始 10 步”

需要我**按你的项目类型（JVM 服务 / CLI / Android / KMP）**直接生成一套可跑模板（build.gradle.kts、settings.gradle.kts、gradle.properties、Dockerfile、.devcontainer、CI、README）吗？把目录结构或目标平台告诉我，我一次性给你齐活。

给你一份Go（Golang）开发环境从 0 到可复现的实战清单。按它走，任意 Go 项目都能在本机、容器、CI 稳稳跑起来并便于交接。

1) 安装 Go（建议用当前稳定版；Go 官方仅保证最近两版兼容）

macOS

1 2	brew install go go version

Ubuntu / Debian

1
2
3

sudo apt update
sudo apt install -y golang
go version

Windows

用 winget：winget install GoLang.Go
或下载官方 MSI，安装后 go version 验证

多版本切换：可用 asdf（跨语言统一）
1
2
3
asdf plugin add golang
asdf install golang <version>
asdf global golang <version>

2) 基本环境变量（仅需了解，不必手改）

go env
# 常见：
# GOROOT  -> Go 安装目录（自动）
# GOPATH  -> $HOME/go（默认）
# GOMODCACHE -> $GOPATH/pkg/mod（模块缓存）
# GOBIN  -> go install 的可执行输出目录（默认 $GOPATH/bin）

把 $GOPATH/bin 加入 PATH，方便直接运行用 go install 安装的工具：

1	echo 'export PATH="$PATH:$(go env GOPATH)/bin"' >> ~/.bashrc

3) 项目骨架（Module 模式）

myapp/
├─ go.mod
├─ cmd/myapp/main.go
├─ internal/sum/sum.go
└─ internal/sum/sum_test.go

初始化模块

1 2	mkdir -p myapp/cmd/myapp myapp/internal/sum && cd myapp go mod init example.com/myapp # 用你的模块路径（公司/仓库地址）

示例代码

1
2
3

// internal/sum/sum.go
package sum
func Of(a, b int) int { return a + b }

// cmd/myapp/main.go
package main

import (
	"fmt"
	"example.com/myapp/internal/sum"
)
var version = "dev"
func main() { fmt.Println("sum:", sum.Of(2, 40), "version:", version) }

最小单测

// internal/sum/sum_test.go
package sum
import "testing"
func TestOf(t *testing.T){ if Of(2,40)!=42 { t.Fatal("want 42") } }

运行与测试：

go run ./cmd/myapp
go test ./...              # 全仓库
go test -race ./...        # 数据竞争检查（强烈建议）
go test -cover ./...       # 覆盖率

4) 依赖与性能工具

拉依赖/整理：go get <pkg>（引入依赖时）+ go mod tidy（清理未用）

常用官方扩展：

go install golang.org/x/tools/cmd/godoc@latest
go install golang.org/x/tools/cmd/stringer@latest
go install honnef.co/go/tools/cmd/staticcheck@latest
go install github.com/air-verse/air@latest            # 热重载（开发服务器）
go install github.com/go-delve/delve/cmd/dlv@latest   # 调试器

代码格式与检查：go fmt ./...、go vet ./...、staticcheck ./...

5) VS Code / IDE 调试

VS Code 装 Go 扩展（golang.go），自动安装工具链。
断点调试（Delve）：
- 启动：dlv debug ./cmd/myapp
- VS Code 直接点 Run and Debug 生成 launch.json 即可。

6) 构建与版本注入

1 2	go build -ldflags "-s -w -X main.version=$(git rev-parse --short HEAD)" ./cmd/myapp ./myapp

-s -w 去符号表减小体积；-X 注入变量（如版本号、构建时间）。

7) 配置与私有仓库

环境变量配置：读取 os.Getenv("KEY")；本地用 .env（配 github.com/joho/godotenv）和 .env.example。
模块代理：默认 GOPROXY=https://proxy.golang.org,direct；公司/国内可换镜像：
1
go env -w GOPROXY=https://<your-proxy>,direct

私有模块拉取（走直连、不经代理与校验）：

1 2	go env -w GOPRIVATE=github.com/your-org/* # 如需禁用代理与校验：GONOPROXY/GONOSUMDB 设置同样的域前缀

8) 质量与提交前检查（golangci-lint）

1
2
3

# 安装
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
# 配置文件 .golangci.yml（示例）

run:
  timeout: 3m
linters:
  enable:
    - govet
    - staticcheck
    - ineffassign
    - gosimple
    - errcheck
issues:
  exclude-use-default: false

运行：golangci-lint run

9) 性能与可观测

基准测试：

// internal/sum/sum_bench_test.go
package sum
import "testing"
func BenchmarkOf(b *testing.B){ for i:=0;i<b.N;i++{ Of(2,40) } }

运行：go test -bench . -benchmem ./internal/sum

pprof（HTTP 端点）：

1 2	import _ "net/http/pprof" // 开一个调试 http 服务：go func(){ http.ListenAndServe(":6060", nil) }()

用 go tool pprof http://localhost:6060/debug/pprof/profile

10) Docker 与 Dev Container（可复现交付）

无 CGO 的静态二进制（首选）

# 构建
FROM golang:1-alpine AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o /out/myapp ./cmd/myapp

# 运行（scratch/极简）
FROM scratch
COPY --from=build /out/myapp /myapp
ENTRYPOINT ["/myapp"]

需要 CGO（如 SQLite、图像处理）：用 debian:stable-slim 或 alpine 安装 gcc，并保持运行镜像含所需 libc（musl/glibc）。

.devcontainer/devcontainer.json

{
  "name": "Go Dev",
  "image": "mcr.microsoft.com/devcontainers/go:1",
  "customizations": { "vscode": { "extensions": ["golang.go"] } }
}

11) CI（GitHub Actions）

name: ci
on: [push, pull_request]
jobs:
  go:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: 'stable'     # 或固定 '1.x'
          cache: true
      - run: go mod download
      - run: go vet ./...
      - run: go test -race -cover ./...
      - run: go build ./cmd/myapp

12) 常见坑 & 快速排查

版本不一致：在 go.mod 顶部的 go <version> 代表语言版本基线；团队统一到当前稳定版。
Vendor/代理冲突：CI 用 -mod=vendor 时必须存在 vendor/；否则默认走模块缓存/代理。
CGO 交叉编译失败：CGO 默认走本机编译链；跨平台需对应交叉编译器（或禁用 CGO）。
Windows 行尾/路径：git config core.autocrlf input；避免过长路径（启用长路径支持）。
私有仓库 401/404：确认 GOPRIVATE 设置、Git 凭据（SSH/Token）与 git config url.ssh://git@... 重写。
go get 与 go install：
- 拉库到当前模块：go get 包@版本，之后 go mod tidy。
- 安装 CLI 工具到 $GOBIN：go install 包/cmd/xxx@版本。
构建缓慢：开启模块缓存（默认）、合理 Docker 层缓存（先 COPY go.mod/sum 再 download）。

13) “10 步极简 Checklist”

安装 Go 稳定版，go version 验证
将 $GOPATH/bin 加入 PATH
go mod init <module> 初始化模块
写 cmd/<app>/main.go 与 internal/ 业务代码
go run ... 跑通；go test -race ./... 通过
go fmt / go vet / staticcheck 清理
（可选）golangci-lint run 集中检查
用 -ldflags "-X main.version=..." 注入版本构建
准备 Dockerfile（静态二进制 + scratch）
接入 CI（setup-go + test -race -cover）

需要的话，把你的项目类型（CLI / Web 服务 / gRPC / Monorepo）和目录结构/依赖贴上来，我可以直接给你生成一套可跑模板（go.mod、项目骨架、Makefile、Dockerfile、Dev Container、CI、README“快速开始”）。

Categories

Tags

编程语言环境搭建汇总(AI)

1) 目标与边界定义

2) 基线检查（Host Readiness）

3) 运行时与版本策略

4) 包管理与依赖锁定

5) 隔离策略（本地）

6) 构建与任务编排

7) 配置与密钥

8) 外部服务与数据

9) 开发工具与 IDE 集成

10) 测试与健康检查

11) 运行与验证

12) 观察与性能

13) CI/CD 对齐

14) 文档与交接

15) 复现性与合规

「10 步极简 Checklist」（贴墙）

各语言「最小命令集」示例

常见故障 → 快速定位

一份可直接套用的 Makefile（示意）

给你的 AI 提问合集（按阶段复用）

一、最快路线（10 分钟上手）

1) 安装编译器与常用工具

Windows（两选一）

macOS

Ubuntu / Debian

2) VS Code 基础（可选但强烈推荐）

二、最小可运行项目脚手架

src/main.c

include/hello.h

src/hello.c（别忘了）

选项 A：CMake（跨平台首选）

CMakeLists.txt

选项 B：Make（最小依赖）

Makefile

三、调试（CLI 与 VS Code）

CLI 调试

VS Code 启动配置示例：.vscode/launch.json

四、单元测试（最小可用）

五、第三方依赖管理（两条成熟路线）

1) vcpkg（微软维护，CMake 结合顺滑）

2) Conan（通用包管）

六、质量与性能（上线前该做的事）

代码风格与静态检查

内存/数据竞争排查

性能初步

七、容器/Dev Container（团队同构、可复现）

Dockerfile（最小开发镜像）

.devcontainer/devcontainer.json

八、常见坑与对策

你可以怎么用这份指南

1) 安装 JDK（首选 LTS：21）

2) 多版本切换（建议：开发机装）

3) 构建工具与 IDE

4) 最小可运行项目脚手架（两选一）

4.1 Gradle（推荐，Kotlin DSL）

4.2 Maven（经典稳健）

5) 运行、测试、调试

本地运行

单元测试（JUnit 5）

断点调试（本地）

远程调试（端口 5005）

6) 配置与环境

7) 质量与安全

8) 性能与可观测

9) 容器与 Dev Container（可复现首选）

10) CI（GitHub Actions 示例）

11) 常见坑 & 快速排查

12) 10 步极简 Checklist

1) 装运行时 & 版本管理（首选 3.11/3.12）

2) 项目骨架（src 布局 + pyproject 一步到位）

3) 虚拟环境与依赖（3 种做法，三选一）

A. uv（推荐，速度快、零脑负担）

B. Poetry（发行版/库友好）

C. pip + venv + pip-tools（经典、透明）

4) 统一命令入口（Makefile / justfile / hatch task）

5) 质量基线（ruff/black/mypy + pre-commit）

6) 测试与覆盖率

`src/main.c`

`include/hello.h`

`src/hello.c`（别忘了）

`CMakeLists.txt`

`Makefile`

VS Code 启动配置示例：`.vscode/launch.json`

`Dockerfile`（最小开发镜像）

`.devcontainer/devcontainer.json`