必须手动设置语言模式、配置solc路径并添加spdx声明，三步缺一不可：vscode默认不识别.sol文件，需点击右下角选solidity；插件依赖solc-select指定路径调用编译器；且每份合约首行须为// spdx-license-identifier: mit等合法声明，否则高亮、跳转、编译均失效。
装对插件、配好路径、选准语言模式，三步到位才能让 Solidity 代码真正“活”起来——语法高亮只是表象，背后是插件能否正确加载语言服务器、识别 pragma 版本、调用 solc 或对接 Hardhat/Foundry 的完整链路。
为什么装了 Solidity 插件但 .sol 文件还是白底黑字？
VSCode 默认不把 .sol 当作 Solidity 文件处理，即使插件已安装并启用。常见表现是：右下角状态栏显示 “Plain Text”，F12 跳转无效，payable、view 等关键字无颜色区分。
- 手动点击右下角语言标识 → 搜索并选择
Solidity（不是Solidity (Beta)或其他变体） - 在设置中搜索
files.associations，添加："*.sol": "solidity" - 确认插件版本 ≥ 0.0.137（旧版存在语言服务器崩溃问题，尤其在 0.8.20+ 合约中）
- 重启 VSCode，再打开
.sol文件验证
solidity-extension 编译失败：solc not found 或 Command failed: solc --version
插件默认从系统 PATH 查找 solc，但多数人没配过，或全局安装路径未被识别。错误不是合约写错了，而是插件根本没执行成功。
- 优先用
solc-select管理多版本：npm install -g solc-select→solc-select install 0.8.24→solc-select use 0.8.24 - 在 VSCode 设置中搜索
solidity compiler path，填入solc-select生成的软链接路径（如/usr/local/bin/solc或C:\Users\XXX\AppData\Roaming\npm\solc.cmd） - 避免直接用
npm install -g solc：Windows 上常生成.cmd包装器，插件有时无法解析；macOS/Linux 下权限或符号链接断裂也易出问题 - 填错路径的典型现象：保存文件后无任何输出，或弹出
Command failed: solc --version
Hardhat / Foundry 项目里 VSCode 不自动编译？这是设计，不是 bug
solidity-extension 会主动检测项目根目录下的配置文件，并切换行为模式——它不试图“接管”框架流程，而是适配已有工具链。
- 发现
hardhat.config.js→ 默认禁用内置编译，只做语法检查和跳转；应改用终端执行npx hardhat compile - 发现
foundry.toml→ 尝试调用forge build，但前提是forge在PATH中，否则静默失败（不会报错） - 纯
.sol文件 + 无项目配置 → 才启用插件自带的solc编译流程 - 别指望一个插件包打天下：开发中该用
hardhat compile就用，该forge test就forge test，VSCode 插件只负责写的时候别拼错require或漏掉分号
SPDX license identifier not provided 报错怎么破？
这是 Solidity 0.6.8+ 的硬性要求，不是警告，不加就编译失败。VSCode 插件会在保存时实时校验，但不会自动补全这行。
- 每份
.sol文件**第一行**必须是 SPDX 声明，例如：// SPDX-License-Identifier: MIT - 不能写成注释块
/* */，必须是单行//开头 - 许可证 ID 必须是 SPDX 官方注册名（
MIT、Apache-2.0、Unlicense等），拼错或自定义名称（如// SPDX-License-Identifier: MyLicense）也会失败 - Hardhat / Foundry 编译器同样校验此行，所以这不是 VSCode 特有逻辑，而是 Solidity 编译器强制规则
最容易被忽略的是：插件的语言服务器启动依赖于正确的 pragma 版本声明与 SPDX 行共存；缺一不可。哪怕你填对了 solc 路径、切对了语言模式，只要第一行没 SPDX 或 pragma solidity ^0.8.24; 和实际 solc 版本不匹配，高亮和跳转都可能降级为半失效状态。
