HKbitEX 开发文档

🌙 主题

开发环境配置 ​

本文档将指导您搭建完整的前端开发环境，包括Node.js版本管理和网络代理配置。

环境要求 ​

  • macOS / Windows / Linux
  • 终端或命令行工具

🎯 重要提醒
💻 Windows用户请注意： 强烈推荐使用 PowerShell 而非CMD，以获得最佳体验！
⚡ PowerShell提供更好的Unicode支持、更强大的脚本功能和更佳的开发体验。

🚀 1. Node.js版本管理 - fnm ​

什么是fnm ​

fnm (Fast Node Manager) 是一个快速简单的Node.js版本管理器，用Rust编写，比nvm更快速且跨平台。

💡 为什么选择fnm？

  • ⚡ 比nvm快数倍
  • 🔧 跨平台支持（Windows/macOS/Linux）
  • 🎯 自动切换Node版本
  • 🦀 使用Rust编写，性能卓越

安装fnm ​

macOS/Linux ​

使用curl安装：

bash
curl -fsSL https://fnm.vercel.app/install | bash

或使用Homebrew（仅macOS）：

bash
brew install fnm

Windows ​

方式一：Winget（推荐）

bash
winget install Schniz.fnm

方式二：Chocolatey

bash
choco install fnm

方式三：Scoop

bash
scoop install fnm

配置shell环境 ​

安装完成后，需要配置shell环境。根据您使用的shell添加以下配置：

Bash ​

在 ~/.bashrc 或 ~/.bash_profile 中添加：

bash
eval "$(fnm env --use-on-cd --shell bash)"

Zsh ​

在 ~/.zshrc 中添加：

bash
eval "$(fnm env --use-on-cd --shell zsh)"

PowerShell (Windows) ​

1. 配置环境变量

在PowerShell配置文件中添加：

powershell
fnm env --use-on-cd --shell powershell | Out-String | Invoke-Expression

2. 创建PowerShell配置文件

如果配置文件不存在，先创建配置文件：

powershell
if (-not (Test-Path $profile)) { New-Item $profile -Force }

3. 编辑配置文件

打开配置文件进行编辑：

powershell
Invoke-Item $profile

4. 处理执行策略问题

在配置文件中添加配置之后重启PowerShell，如果遇到执行策略报错：

⚠️ 常见错误

无法加载文件 C:\Users\zzy\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1，
因为在此系统上禁止运行脚本。

解决方案：

方案一：临时允许（推荐安全做法）

powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

💡 此设置只对当前PowerShell会话有效，关闭窗口后恢复默认

方案二：永久允许当前用户运行脚本

推荐使用RemoteSigned策略（允许本地脚本和已签名的远程脚本）：

powershell
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

如需更宽松策略：

powershell
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted

⚠️ 不建议直接使用Unrestricted或Bypass，除非确定脚本来源安全

方案三：全局策略修改（需管理员权限）

powershell
Set-ExecutionPolicy -Scope LocalMachine -ExecutionPolicy RemoteSigned

检查当前执行策略：

powershell
Get-ExecutionPolicy -List

常用fnm命令 ​

bash
# 列出可安装的Node.js版本
fnm list-remote

# 安装最新的LTS版本
fnm install --lts

# 安装指定版本
fnm install 18.17.0

# 列出已安装的版本
fnm list

# 切换到指定版本
fnm use 18.17.0

# 设置默认版本
fnm default 18.17.0

# 自动使用项目中.nvmrc指定的版本
fnm use --install-if-missing

项目级别的Node版本管理 ​

在项目根目录创建 .nvmrc 文件：

18.17.0

配置了 --use-on-cd 参数后，进入项目目录时会自动切换到指定版本。

🌐 2. 网络代理配置 - whistle + ZeroOmega ​

什么是whistle ​

Whistle是一个基于Node.js实现的跨平台抓包调试代理工具，支持HTTP、HTTPS、WebSocket等协议。

🎯 whistle的优势

  • 📡 支持HTTP/HTTPS/WebSocket协议
  • 🔍 强大的抓包调试功能
  • 🎛️ 灵活的规则配置
  • 🖥️ 直观的Web管理界面

安装whistle ​

使用npm全局安装：

bash
npm install -g whistle

启动whistle ​

bash
# 启动whistle，默认端口8899
w2 start

# 指定端口启动
w2 start -p 8800

# 后台启动
w2 start -D

whistle基本配置 ​

  1. 启动后访问 http://localhost:8899 进入管理界面
  2. 在Rules页面配置代理规则
  3. 在Values页面管理变量和响应内容

常用代理规则示例 ​

bash
# 代理本地开发
example.com 127.0.0.1:3000

# 修改响应头
example.com/api/** resHeaders://{CORS}

# 注入本地文件
example.com/static/js/main.js file:///path/to/local/main.js

# 代理到测试环境
api.example.com test-api.example.com

安装浏览器扩展 - ZeroOmega ​

Chrome/Edge ​

  1. 前往 Chrome Web Store 搜索 "ZeroOmega"
  2. 点击"添加至Chrome"进行安装

Firefox ​

  1. 前往 Firefox Add-ons 搜索 "ZeroOmega"
  2. 点击"添加到Firefox"进行安装

配置ZeroOmega ​

  1. 创建代理配置

    • 点击扩展图标，选择"选项"
    • 点击"新建情景模式"
    • 选择"代理服务器"类型
    • 命名为"whistle"

  2. 设置代理服务器

    • 协议：HTTP
    • 代理服务器：127.0.0.1
    • 端口：8899

  3. 配置自动切换

    • 创建"自动切换"情景模式
    • 添加切换规则：
      条件类型：主机通配符
条件设置：localhost
情景模式：whistle

  4. 应用配置

    • 点击"应用选项"保存配置
    • 在扩展图标中选择对应的情景模式

HTTPS支持配置 ​

下载并安装证书 ​

  1. 访问 http://localhost:8899
  2. 点击"HTTPS"标签
  3. 下载根证书
  4. 根据操作系统安装证书：

macOS:

bash
# 双击证书文件，或使用命令行
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain rootCA.crt

Windows:

  1. 双击证书文件
  2. 选择"本地计算机"
  3. 将证书放入"受信任的根证书颁发机构"

Linux:

bash
sudo cp rootCA.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

移动端调试配置 ​

iOS设备 ​

  1. 设置 > Wi-Fi > 点击已连接网络的"i"图标
  2. 配置代理 > 手动
  3. 服务器：电脑IP地址
  4. 端口：8899
  5. 安装证书：Safari访问 http://电脑IP:8899，下载并安装证书

Android设备 ​

  1. 设置 > Wi-Fi > 长按已连接网络 > 修改网络
  2. 高级选项 > 代理 > 手动
  3. 代理服务器主机名：电脑IP地址
  4. 端口：8899
  5. 安装证书：浏览器访问 http://电脑IP:8899，下载并安装证书

✅ 3. 开发环境验证 ​

验证Node.js环境 ​

bash
# 检查fnm版本
fnm --version

# 检查当前Node.js版本
node --version

# 检查npm版本
npm --version

验证代理环境 ​

  1. 启动whistle：w2 start
  2. 打开浏览器，启用ZeroOmega的whistle配置
  3. 访问任意网站，在whistle管理界面查看是否有请求记录

❓ 4. 常见问题 ​

🔧 fnm相关问题 ​

Q: fnm命令不存在

解决方案：

  1. 检查PATH环境变量配置
  2. 重新启动终端
  3. 确认fnm安装成功：which fnm
Q: 自动切换Node版本不生效

解决方案：

  • 确保配置了 eval "$(fnm env --use-on-cd --shell <your-shell>)"
  • 检查.nvmrc文件是否存在且格式正确
  • 重新启动终端或重新加载shell配置

🌐 whistle相关问题 ​

Q: HTTPS网站无法正常代理

解决方案：

  1. 确保已正确安装和信任whistle证书
  2. 检查浏览器证书设置
  3. 重启浏览器
Q: 移动端无法连接代理

解决方案：

  1. 检查防火墙设置，确保8899端口可访问
  2. 确认电脑和手机在同一网络
  3. 使用电脑的内网IP地址，不是127.0.0.1
Q: 代理规则不生效

解决方案：

  1. 检查规则语法是否正确
  2. 确保whistle规则已启用
  3. 清除浏览器缓存后重试

🏆 5. 最佳实践 ​

  1. 项目规范

    • 每个项目都应包含 .nvmrc 文件
    • 使用 package.json 中的 engines 字段指定Node版本要求

  2. 代理规则管理

    • 按项目分组管理whistle规则
    • 使用whistle的分组功能组织规则

  3. 团队协作

    • 统一Node.js版本管理工具
    • 共享whistle代理规则配置

  4. 安全考虑

    • 仅在开发环境使用代理
    • 定期更新证书

🎉 恭喜！ 通过以上配置，您已经成功搭建了一个完整且高效的前端开发环境！

📚 相关文档 ​

🚀 构建现代化数字资产交易平台

Copyright © 2025 HKbitEX Development Team