阶进遐

主题

个人博客自建指南（2）：编辑器与工具链 —— VSCode、包管理与Vite脚手架 ​

前言 ​

上一篇我们把 Node.js 环境搭好了，fnm 丝滑切换版本，终端里 node -v 能看到输出。
但光有 Node.js 这个运行环境还不够, 开发环境也不能少 —— 你需要一个编辑器来写代码，需要一个包管理器来装依赖，需要一个脚手架来拉起项目骨架。

这篇就从这三件事入手：VSCode 配置、国内源包管理、Vite 脚手架搭建。走完这三步，你就能在浏览器里看到自己的第一个前端页面了。

一、VSCode 下载安装 ​

VSCode（Visual Studio Code）是微软推出的一款免费、开源的代码编辑器，轻量但功能强大，通过安装插件可以支持几乎所有编程语言。
它是目前前端开发者的首选编辑器，本专栏后续的所有代码编写都在 VSCode 中进行。

1.1 下载与安装 ​

官网下载： https://code.visualstudio.com

下载 VSCodeUserSetup-x64-最新版本.exe，双击安装，一路默认即可。安装时勾选“添加到 PATH”和“将Code注册成为受支持的....”这两个选项，方便后续在终端里直接用 code . 打开项目。

1.2 必备插件 ​

安装完成后，打开 VSCode，点击左侧扩展图标（ 或按 Ctrl+Shift+X ），搜索并安装以下插件：

插件用途
Chinese (Simplified) Language Pack中文界面
Vue (Official)Vue 3 官方语言支持（替代 Vetur）
ESLint代码检查
Prettier - Code formatter代码格式化

安装完成后重启 VSCode，界面变为中文。

1.3 配置终端为 PowerShell ​

VSCode 默认终端可能是 cmd 或 旧版 PowerShell，需要切换到 PowerShell 7+（Core），否则 fnm 的 $PROFILE可能不生效。

打开 VSCode 设置（Ctrl+,），弹窗的右上角找到 打开设置（json）的图标，点击进入编辑，在 settings.json 中追加：

json
{
  "terminal.integrated.defaultProfile.windows": "PowerShell",
  "terminal.integrated.profiles.windows": {
    "PowerShell": {
      "source": "PowerShell",
      "icon": "terminal-powershell"
    }
  },
  "terminal.integrated.shellIntegration.enabled": true
}

保存后，打开 VSCode 内置终端（Ctrl+`），应该看到 PowerShell 提示符。输入 fnm --version确认 fnm 可用。

💡 两个常见小状况：
fnm 提示找不到命令：先关掉所有旧终端，开一个新终端试试（PATH 改了旧终端读不到）；还不行就回 2.1 节检查 PATH 是不是把 fnm.exe 本身加进去了（应该加目录 D:\fnm-windows，不是文件）。
fnm 能出来但 use-on-cd 不生效（进带 .node-version 的目录不自动切）：检查 terminal.integrated.shellIntegration.enabled 是否为 true——这是 VSCode 往 PowerShell 注入 prompt 钩子的开关，fnm 的 fnm env --use-on-cd 靠这个。

1.4 VSCode 自动换行三种方式，按需选： ​

1.4.1 临时开关（最常用） ​

Alt + Z（Mac 是 Option + Z），当前文件立即切换，松手就还原，不碰配置。

1.4.2 全局永久开启 ​

Ctrl+, → 搜 word wrap → 改成 on。

或者直改 settings.json (Ctrl+, → 右上角 打开设置（json）的图标)：

json
{
  "editor.wordWrap": "on"
}

可选值：off（默认）、on、wordWrapColumn（按列数折）、bounded（按视口折）。

1.4.3 只对 Markdown 开（写博客常用） ​

修改 settings.json (Ctrl+, → 右上角 打开设置（json）的图标)：

json
{
  "[markdown]": {
    "editor.wordWrap": "on"
  }
}

💡 写博客专栏的话，建议只对 [markdown]开，代码文件保持 off，不然 JSX/TS 一长行折来折去看结构费劲。

二、国内源包管理 ​

包管理器是什么？
简单说，它是一个“自动下载和管理代码依赖的工具”。当你写代码时，经常会用到别人写好的功能模块（比如 Vue、Vite 这些框架），包管理器能帮你一键下载、安装、更新这些模块，不用手动去官网找压缩包。

Node.js 自带的包管理器是 npm（Node Package Manager）。你只需要执行 npm install <包名>，它就会从全球统一的 npm 仓库下载代码。
但问题来了：这个仓库的服务器在国外，国内直接下载速度很慢，经常卡住或超时。所以我们需要配置一个国内的镜像源（比如 npmmirror 镜像站），把下载请求转发到国内的服务器，速度会快很多。

同时，npm 本身有一些局限：安装速度慢、磁盘占用大（每个项目都把依赖复制一份）。因此推荐升级到 pnpm —— 它通过硬链接共享依赖，安装速度比 npm 快 2-3 倍，磁盘占用也更小，而且是 Vue、Vite、Nuxt 官方推荐的包管理器。

2.1 npm 镜像（保底方案） ​

打开 powershell 终端， 配置一次全局生效，以后所有 npm install都走国内源：

powershell
npm config set registry https://registry.npmmirror.com
npm config get registry

验证：输出应为 https://registry.npmmirror.com

2.2 pnpm 安装 + 镜像（推荐方案） ​

pnpm 的优势 ​

  • 快：依赖通过硬链接共享，重复包只存一份，安装速度比 npm 快 2-3 倍
  • 省：node_modules不再是扁平的，磁盘占用小很多（对后续 ECS 部署友好）
  • 官方推荐：Vue、Vite、Nuxt 官方文档示例均使用 pnpm

安装 pnpm ​

powershell
# 从 npm 装（复用 2.1 的 npm 镜像，国内下载稳）
npm install -g pnpm

配置国内镜像（与 npm 保持一致）： ​

powershell
pnpm config set registry https://registry.npmmirror.com
pnpm config get registry

配置全局环境变量（关键一步）： ​

powershell
pnpm setup

⚠️ pnpm setup会将 pnpm 的全局 bin 目录（C:\Users\你的用户名\AppData\Local\pnpm\bin）添加到系统的 PATH 环境变量中。
如果不执行这一步，后续使用 pnpm add -g 安装全局工具（如 npm-check-updates）时会报错 not in PATH。

验证安装： ​

powershell
# 关掉当前终端重开，让 PATH 生效
pnpm --version

能看到版本号（如 11.10.0）即说明安装成功。

2.3 镜像源 502 的处理办法 ​

配置完国内源后，偶尔会遇到这样的报错：

GET https://registry.npmmirror.com/create-vite/-/create-vite-9.1.2.tgz
error (ERR_PNPM_FETCH_502). Will retry in 10 seconds. 2 retries left.

原因：这不是你网络的问题，也不是 pnpm 的 bug。npmmirror 是国内最大的 npm 镜像站，每天处理数亿次请求，边缘网关偶尔会返回 502（网关收到无效响应），属于瞬时故障，通常几秒到几分钟内自动恢复。

处理方法（按优先级尝试）：

方法一：等待重试（最简单） ​

pnpm 自带重试机制，遇到 502 会自动退避重试（10 秒一次，最多 3 次）。多数情况下等它重试完就成功了，不用做任何操作。

方法二：单次命令临时换源（推荐） ​

如果重试后仍然失败，可以不修改全局配置，只在当前命令后加 --registry 参数临时切换，例如：

powershell
# 临时切换到腾讯云镜像（单次生效，不影响全局配置）
pnpm create vite@latest jiejinx-blog -- --template vue-ts --registry=https://mirrors.cloud.tencent.com/npm/

其他可用的国内镜像源：

名称地址适用场景
npmmirror（主用）https://registry.npmmirror.com日常使用
腾讯云https://mirrors.cloud.tencent.com/npm/主源 502 时临时切换
华为云https://mirrors.huaweicloud.com/repository/npm/备用
阿里云 npmhttps://npm.aliyun.com阿里云 ECS 内网首选

方法三：全局切换备用源 ​

如果某个时间段 npmmirror 持续不稳定，可以全局切换到备用源：

powershell
# 切换到腾讯云镜像
pnpm config set registry https://mirrors.cloud.tencent.com/npm/
pnpm config get registry

# 等 npmmirror 恢复后再切回来
pnpm config set registry https://registry.npmmirror.com

方法四：使用 nrm 管理多源（进阶） ​

powershell
# 全局安装 nrm
pnpm add -g nrm

# 添加备用源
nrm add tencent https://mirrors.cloud.tencent.com/npm/
nrm add huawei https://mirrors.huaweicloud.com/repository/npm/

# 测速后一键切换
nrm test
nrm use tencent

⚠️ 注意：pnpm 不支持自动故障转移，.npmrc 里写多个 registry= 只有第一个生效。需要切换时手动执行 pnpm config set registry 或使用 nrm 管理。

三、Vite 脚手架搭建 ​

环境就绪，现在来创建一个真正的项目。这里我们使用 Vite 作为构建工具。

Vite 是 Vue 团队推出的一款前端构建工具，用来替代 Webpack。它的核心特点是快 —— 开发时不用等整个项目打包完，改哪行代码就更新哪行，几乎是秒级响应。VitePress（第四篇会用到）底层也是基于 Vite 的，所以现在熟悉它，后面会很顺手。

Vite 本身不强制你用哪个框架，它支持 Vue、React、Svelte 等多种框架。本专栏选用 Vue + TypeScript 模板，因为 Vue 3 的组合式 API 和 TypeScript 的类型系统搭配起来很舒服，而且 Vue 官方文档和示例也都是这套组合。

下面就用 pnpm 创建一个 Vite + Vue + TypeScript 项目。

3.1 创建项目 ​

选择一个你喜欢的目录（比如 F:\web），打开终端：

powershell
# 进入工作目录
cd F:\web

# 用 pnpm 创建 Vite + Vue + TypeScript 项目
# jiejinx-blog 为项目名，可自行替换
pnpm create vite@latest jiejinx-blog -- --template vue-ts
# 遇到 Install with pnpm and start now? 默认选yes 回车即可

如果习惯用 npm，也可以：npm create vite@latest jiejinx-blog -- --template vue-ts

看到提示 Done. Now run: 就说明项目骨架拉好了。

最新版本的vite脚手架会自动安装依赖和启动开发服务器，若没有自动进行，可参考接下来的3.2~3.3 步骤.

3.2 安装依赖 ​

powershell
cd jiejinx-blog
pnpm install

这一步会根据 package.json下载所有依赖。因为有国内镜像，应该几秒就完成。

3.3 启停开发服务 ​

启动开发服务

powershell
pnpm dev

终端输出类似：

powershell
VITE v8.1.3  ready in xxx ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: http://192.168.x.x:5173/

浏览器打开 http://localhost:5173/，你会看到 Vite + Vue 的欢迎页面。

停止开发服务

开发服务启动后，终端会进入“阻塞”状态（光标停在原地，无法输入新命令）。需要停止时，在终端窗口中按下：

powershell
Ctrl + C

终端会输出终止信号，光标恢复可输入状态，服务器停止运行。

💡 注意：Ctrl + C 是停止大多数命令行程序的通用快捷键（包括 pnpm dev、pnpm run build 等）。如果按一次没反应，再按一次即可。不需要关掉整个终端窗口。

3.4 项目结构速览 ​

vscode 打开此项目：

powershell
# 确定当前目录是项目目录
cd F:\web\jiejinx-blog
code .

目录结构：

jiejinx-blog/
├── .vscode/              # VSCode 编辑器配置
├── node_modules/         # 依赖包存储
├── public/               # 静态资源目录 (不会被编译)
│   ├── favicon.svg       # 网站图标
│   └── icons.svg
├── src/                  # 源码目录
│   ├── assets/           # 静态资源 (会被编译处理，如图片、字体)
│   ├── components/       # 公共组件目录
│   ├── App.vue           # 根组件
│   ├── main.ts           # 应用入口文件 (TypeScript)
│   └── style.css         # 全局样式文件
├── .gitignore            # Git 忽略文件配置
├── index.html            # 项目入口 HTML (Vite 特有)
├── package.json          # 项目配置与依赖
├── pnpm-lock.yaml        # pnpm 锁定依赖版本
├── README.md             # 项目说明文档
├── tsconfig.app.json     # 应用专属 TS 配置
├── tsconfig.json         # 根目录 TS 配置
├── tsconfig.node.json    # Node 环境 TS 配置
└── vite.config.ts        # Vite 构建工具配置

不需要深入理解每个文件的作用，先知道 src/App.vue 是首页组件、pnpm dev 是开发命令就够了。

总结 ​

这篇我们从三件事入手：

  1. VSCode：编辑器 + 插件 + 终端配置，写代码的环境准备好了
  2. 国内源包管理：npm 保底 + pnpm 推荐，装依赖不再龟速
  3. Vite 脚手架：pnpm create vite→ pnpm install→ pnpm dev，浏览器看到页面了

至此开发环境已经完整闭环：fnm 管理 Node.js → VSCode 写代码 → pnpm 装依赖 → Vite 跑项目。