【常见问题对策】VSCode常见错误及其解决方法汇总

大家好！我是一个从零编程知识开始，借助AI的力量自学并成功建立网站的人。我非常理解大家“搞不懂”的心情。因为就在几个月前，我也和大家一样，在同一个地方苦恼不已。

特别是刚开始使用VSCode（Visual Studio Code）的时候，接二连三出现的错误信息，真的会让人感到沮丧，对吧？心里想着：“我只是想写点代码而已啊…！”

在这篇文章中，我将用最通俗易懂的方式，尽量避免使用专业术语，来解说我实际遇到并克服的那些VSCode中真正常见的错误及其解决方法。目的只有一个，就是希望大家能体验到“代码跑起来了！”的成功感。读完这篇文章，错误将不再可怕。让我们一个一个地，一起来解决吧！

【超基础】首先要尝试的！解决问题的三大法宝

在进入具体错误的话题之前，有一些“基本功”是我希望大家无论遇到什么问题都首先尝试的。你会惊讶地发现，许许多多的问题，靠这些就能解决。

1. 不管三七二十一，先“重启”

虽然可能难以置信，但这是最有效的方法。一旦觉得“好像有点不对劲？”，首先请彻底关闭VSCode，然后再重新启动它。很多时候，比如扩展加载失败，或者只是一些暂时性的故障，单靠重启就能轻松解决。这和电脑状态不好时重启一下是同样的道理。

2. 暂时禁用所有扩展

VSCode之所以方便，很大程度上得益于各种便利的“扩展”。但是，这些扩展之间有时会“打架”，从而引发意想不到的错误。

要确认问题是否出在扩展上，“扩展二分法”这个功能非常方便。

打开命令面板 (mac: Cmd + Shift + P, Win: Ctrl + Shift + P)。
输入 >Extensions: Bisect 并执行。
按照屏幕上的指示操作，VSCode会自动将扩展逐个禁用一半，从而帮助你定位到导致问题的那个扩展。

如果这样问题解决了，那原因就是某个扩展了。找到问题扩展后，可以禁用它或重新审视其设置。

3. 隔离问题

试着回想一下，这个错误是“从什么时候开始”、“做了什么之后”才出现的？

是刚装了新扩展之后？
是只在打开特定文件时才出现？
HTML文件没问题，但JavaScript文件就会报错？

像这样，如果能确定问题发生的条件，就能找到解决问题的捷径。

【分场景】那些让我欲哭无泪的...常见错误与“复制粘贴”就能搞定的解决方法

从这里开始，我将介绍一些我在制作网站过程中实际遇到、并且花了不少时间才解决的具体错误。相信你的屏幕上，可能正显示着其中某个错误。

情况1：中文变成神秘符号！“乱码”错误

明明在HTML文件里写的是中文，但在浏览器里显示出来却成了ï¿½ï¿½ï¿½这样的神秘符号…。这可以说是每个新手都必经的“乱码”之路。

原因:
这是因为文件保存时使用的“字符编码（Encoding）”与浏览器解析时认为的字符编码不一致造成的。过去，像GBK这样的编码格式在中国很常用，但现在，使用世界标准的UTF-8才是主流。

解决方法：
让我们把VSCode的设置改掉，让以后创建的所有文件都默认以UTF-8格式保存吧。一旦设置好，就再也不用为乱码烦恼了。

在mac上按 Cmd + , (逗号)，在Windows上按 Ctrl + , (逗号) 打开设置界面，然后点击右上角的文件图标打开settings.json，将以下代码复制粘贴进去。

{
  // 文件相关设置
  "files.encoding": "utf8", // 将打开文件的默认字符编码设置为UTF-8
  "files.autoGuessEncoding": true, // 打开文件时自动猜测字符编码
  "files.eol": "\n" // 将文件的换行符统一为LF(\n)
}

如果{}里面已经有内容了，只需要把里面的设置项（比如"files.encoding": "utf8",等）追加进去就行了。

情况2：命令无效！“command not found”错误

在Web开发中，我们经常在VSCode内置的“终端”里使用像npm或git这样的命令。但是，有时输入命令后，却会看到zsh: command not found: npm这样的提示，好像在说“我不认识这个命令”。

原因:
这是因为电脑上没有安装那个命令（程序），或者虽然安装了，但电脑不知道“那个命令在哪里”（也就是PATH路径没有配置好）。

解决方法：
首先，确认一下是不是真的安装了。比如，对于Node.js（它包含了npm命令），可以在终端里试试输入以下命令。

node -v

如果显示了版本号（例如：v20.11.0），就说明已经安装了。如果提示command not found，那就说明根本没安装。请从Node.js官网下载安装。

如果安装了还是报错，可以尝试重启一下VSCode。刚安装完后，VSCode有时可能还没能识别到新的PATH路径。

情况3：代码不变整洁！Prettier / ESLint 不工作

保存文件的瞬间，乱七八糟的代码像施了魔法一样变得整整齐齐…。实现这个效果的就是像Prettier或ESLint这样的格式化工具/代码检查工具。但是，明明设置好了却完全不工作，这也是一个常见的烦恼。

原因:
可能的原因有几个。
1. VSCode的Prettier或ESLint扩展没有安装，或者被禁用了。
2. 项目里没有配置文件 (.prettierrc, .eslintrc.js)。
3. VSCode的设置里，“保存时格式化”没有被启用。
4. 多个格式化工具发生了冲突。

解决方法：
请尝试将以下设置，复制粘贴到我们之前提过的settings.json文件里。这是一个能解决各种问题的“全家桶”设置。我做网站的时候，这个设置也帮了我很多次。

{
  // ----- 关于格式化和代码检查的设置 -----

  // 将Prettier设置为默认格式化工具
  // 这样可以防止和其他格式化工具打架
  "editor.defaultFormatter": "esbenp.prettier-vscode",

  // 在保存文件时自动执行格式化
  "editor.formatOnSave": true,

  // 指定希望ESLint也进行检查和修复的文件类型
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],

  // 在保存文件时也执行ESLint的自动修复
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

【要点解说】
其中特别重要的是"editor.defaultFormatter": "esbenp.prettier-vscode"。VSCode本身也带有代码格式化功能。因此，如果再装上Prettier扩展，它有时会搞不清楚“该听谁的？”。通过这一行设置，就等于声明了“格式化的事，全权交给Prettier老师！”，从而可以避免冲突。

当然，前提是你已经安装了Prettier和ESLint的扩展哦！

情况4：找不到导入的模块！“Cannot find module”错误

在使用JavaScript或TypeScript进行开发时，我们经常用import从其他文件导入组件（模块）。这时，有时会出现像Cannot find module './components/Button'这样的错误。

原因:
这绝大多数情况下都只是简单的路径指定错误。但是，当项目变得复杂后，像../../../../utils/helper.js这样的相对路径中的../会变得越来越深，也就越来越容易出错（我称之为“("../")地狱”）。

解决方法：
为了从这个“("../")地狱”中解脱出来，让我们来创建一个名为jsconfig.json（如果是TypeScript项目，则是tsconfig.json）的配置文件吧。这个文件是用来告诉VSCode“项目的基准位置（根目录）在这里”的。

在你的项目顶层（和package.json在同一层级）创建一个名为jsconfig.json的文件，并将以下内容复制粘贴进去。

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "exclude": ["node_modules"]
}

【要点解说】
这个设置有什么好处呢？举个例子，假设你想从一个完全不同层级的src/pages/index.js文件中，导入src/components/ui/Button.jsx这个文件。

设置前：import Button from '../../components/ui/Button'; （很容易搞错层级…）
设置后：import Button from '@/components/ui/Button'; （@指向src文件夹，所以无论在哪里都可以用同样的方式书写！）

这样一来，即使移动了文件位置，也几乎不需要修改import语句了。这真的是革命性的！

【应用篇】别再怕了！遇到错误，就这样问AI！

我之所以能自学成功做出网站，毫无疑问是AI助手的功劳。即使出现错误信息，也完全没必要惊慌。那正是用来问AI的最好“材料”。

但是，仅仅是复制粘贴错误信息，有时并不能得到好的回答。想要引出好的答案，提问方式是有技巧的。

最强提问模板

当你遇到错误时，可以试试用下面的模板来向AI提问。

主题: 在 [使用的技术] 中发生了 [错误内容] 的错误

1. 背景/目的:
（例：我正在使用Next.js和TypeScript，试图导入一个组件。）

2. 出现的问题:
（例：当我运行npm run dev时，终端显示了以下错误信息。）

在这里原封不动地粘贴错误信息

3. 相关代码:
（例：这是报错文件的相关部分代码。）

在这里粘贴代码

4. 已经尝试过的方法:
（例：我尝试了重新运行npm install和重启VSCode，但问题没有解决。）

5. 问题:
请告诉我这个错误的根本原因，以及解决它的具体步骤。

像这样，将“想做什么”、“发生了什么”、“尝试了什么”这三要素组合在一起传达给AI，它就能准确理解状况，并给出精准的解决方案。错误日志是最好的提示宝库。请务必，将AI变成你最强的搭档。

总结

这次，我结合自己的实际体验，解说了新手在VSCode中容易遇到的错误及其具体解决方法。

在学习编程的道路上，错误是无法避免的。但是，每一个错误都必有其原因，也必有其解决方法。错误信息不是敌人，而是亲切地告诉你“这里不对哦！”的信号。

如果这篇文章能帮助你将“搞不懂”变成“搞懂了！”，那将是我最高兴的事。每克服一个错误，你都在切实地升级。请带着自信，享受编码的乐趣吧！