VSCode配置Solidity需三步同步生效：手动切换语言模式为Solidity、显式配置solc编译器路径、每个.sol文件首行添加严格格式的SPDX声明，缺一即导致高亮失效或编译失败。
装对插件只是起点，真正卡住人的永远是语言模式没切、solc 路径没填、SPDX 声明漏写——三者缺一不可，少一个，.sol 文件就只是带颜色的纯文本。
VSCode 里 .sol 文件还是白底黑字？先确认语言模式
插件装了、重启了、右下角状态栏却显示 “Plain Text” 或 “Unknown Language”，说明 VSCode 根本没把文件当 Solidity 处理。这不是插件失效，是绑定没做。
- 打开任意
.sol文件，点击右下角语言标识（通常在窗口最下方） - 搜索并选择
Solidity—— 注意不是Solidity (Beta)或其他变体 - 若列表里没有
Solidity，检查插件是否启用、VSCode 是否重启、插件版本是否 ≥0.0.137（旧版在0.8.20+合约中易崩溃） - 一劳永逸：在 VSCode 设置中搜索
files.associations，添加："*.sol": "solidity"
保存文件弹出 solc not found？路径必须显式指定
插件默认从系统 PATH 查找 solc，但绝大多数人没配过全局路径，结果就是高亮正常、编译静默失败。
- 别依赖
npm install -g solc：Windows 上生成.cmd包装器，插件常解析失败；macOS/Linux 下权限或符号链接断裂也易出问题 - 推荐用
solc-select管理多版本：npm install -g solc-select→solc-select install 0.8.24→solc-select use 0.8.24 - 在 VSCode 设置中搜索
solidity compiler path，填入它生成的软链接路径：/usr/local/bin/solc（macOS/Linux）或C:\Users\XXX\AppData\Roaming\npm\solc.cmd（Windows） - 验证方式：保存一个
.sol文件，看输出面板是否有solc --version输出或编译错误；无任何反应 = 路径仍无效
Hardhat 项目里 VSCode 不自动编译？这是设计，不是 bug
solidity-extension 会主动检测项目根目录下的配置文件，并切换行为模式——它不接管框架流程，只适配已有工具链。
- 发现
hardhat.config.js→ 默认禁用内置编译，只做语法检查和跳转；应改用终端执行npx hardhat compile - 发现
foundry.toml→ 尝试调用forge build，但前提是forge在PATH中，否则静默失败（不会报错） - 纯
.sol文件 + 无项目配置 → 才启用插件自带的solc编译流程 - 别指望插件包打天下：开发中该用
hardhat compile就用，该forge test就forge test，插件只负责写的时候别拼错payable或漏掉分号
编译报错 SPDX license identifier not provided？必须手动加，不能跳过
这不是警告，是 Solidity ≥ 0.6.8 的硬性编译失败项。VSCode 插件不会帮你补这行，而且格式极其严格。
- 必须写在每个
.sol文件最顶部，注释前不能有任何空行、BOM 或不可见字符 - 标准写法（必须严格匹配）：
// SPDX-License-Identifier: MIT - 可用值仅限：
MIT、Apache-2.0、Unlicense；写GPL-3.0或自定义字符串也会失败 - VSCode 插件支持快捷补全：光标定位到文件首行，按
Ctrl+Space触发提示，选中即可插入 - OpenZeppelin 合约自带 SPDX，但你自己写的
contracts/MyToken.sol必须单独加——少一个文件，整个npx hardhat compile就中断
最容易被忽略的是三者之间的耦合关系：语言模式决定插件能否加载语言服务器，solc 路径决定能否触发编译，SPDX 声明决定编译是否通过。它们各自独立配置，又必须全部生效，缺一不可。
