根本原因是语言模式未激活、文件关联缺失或Hardhat未项目级安装：需点击右下角选Solidity而非Plain Text，设置"*.sol": "solidity"，在项目根目录npm install --save-dev hardhat，并为每个.sol文件首行添加// SPDX-License-Identifier: MIT。
VSCode 默认不识别 .sol 文件，装了插件也没语法高亮或补全——根本原因不是插件没装，而是语言模式没激活、文件关联缺失，或 Hardhat 没按项目级方式安装。
点击右下角切换语言模式为 Solidity
VSCode 打开任意 .sol 文件时，右下角状态栏默认显示 “Plain Text” 或 “Unknown”，此时插件功能完全不生效。必须手动触发语言识别：
- 点击右下角语言标识（如 “Plain Text”）
- 在弹出菜单中搜索并选择
Solidity（注意：不是Solidity (Beta)、Solidity Language Server等变体） - 若列表里没有
Solidity，说明插件未启用：检查插件是否已安装且勾选“启用”，重启 VSCode，确认插件版本 ≥0.0.137（旧版存在语言服务器崩溃问题） - 顺手在设置中搜
files.associations，添加一行："*.sol": "solidity"，避免每次都要点选
npx hardhat compile 报错 Cannot find module 'hardhat'
这不是没装 Hardhat，而是 Node.js 模块作用域错了——全局安装 npm install -g hardhat 会导致 VSCode 终端找不到本地 node_modules/.bin 下的可执行文件。
- 确保你在合约项目根目录下操作（比如
my-token/），不是随便打开一个文件夹就敲命令 - 先运行
npm init -y生成package.json - 再运行
npm install --save-dev hardhat（必须是--save-dev，不是-g） - 验证：执行
npx hardhat，应输出任务列表；若报错，检查当前目录是否存在node_modules/hardhat/ - VSCode 集成终端默认工作路径可能不是项目根，启动前先
cd进去，或右键项目文件夹 → “Open in Integrated Terminal”
编译失败：SPDX license identifier not provided
这是 Solidity 0.6.8+ 的硬性要求，不是警告，少写一行就整个项目编译中断。Hardhat 默认开启严格 SPDX 检查，而很多示例代码漏掉了它。
- 在每个
.sol文件最顶部、任何内容（包括空行）之前，加且仅加一行：// SPDX-License-Identifier: MIT - 可用值只有
MIT、Apache-2.0、Unlicense，写ISC或自定义字符串照样报错 - OpenZeppelin 的依赖合约自带 SPDX，但你自己写的
contracts/MyToken.sol必须手动加 - VSCode Solidity 插件支持自动补全：在文件首行按
Ctrl+Space，会提示 SPDX 行，直接回车即可
Hardhat 启动本地节点后无法部署合约
常见现象是 npx hardhat run scripts/deploy.js 报连接超时或 network undefined，本质是网络配置和节点服务没对齐。
-
npx hardhat node必须提前运行，它会在http://localhost:8545启动内置测试网，并预载 10 个带 ETH 的账户 - 检查
hardhat.config.js中是否配置了localhost网络，例如：{ localhost: { url: "http://127.0.0.1:8545" } } - 部署脚本里要显式指定网络：
npx hardhat run scripts/deploy.js --network localhost，不能只写npx hardhat run scripts/deploy.js - 如果用的是 TypeScript 配置（
hardhat.config.ts），确保已安装@nomicfoundation/hardhat-toolbox并正确导出配置对象
最容易被忽略的是：SPDX 必须出现在每一份独立 .sol 文件的绝对顶部，连一个空行都不能有；以及 npx hardhat 命令永远只认当前目录下的 node_modules，切勿跨目录执行。
