DarkM

# 开发环境配置

完整的开发环境配置指南，帮助您快速搭建 DarkM.UI 前端开发环境。

# 📋 环境要求

软件 版本要求 说明
Node.js 14.x 推荐使用 nvm 管理
npm 6.14+ 随 Node.js 安装
VS Code 最新版 推荐编辑器
Git 2.0+ 版本控制

# 🛠️ 开发工具

# 推荐编辑器：VS Code

下载 VS Code (opens new window)

# 必装插件

插件 说明 安装命令
Vetur Vue 开发工具 Vue
ESLint 代码规范检测 ESLint
Prettier 代码格式化 Prettier - Code formatter
Volar Vue 3 支持（可选） Volar
Auto Close Tag 自动闭合标签 Auto Close Tag
Auto Rename Tag 自动重命名标签 Auto Rename Tag
Path Intellisense 路径智能提示 Path Intellisense
GitLens Git 增强 GitLens

# 插件配置

VS Code 设置（.vscode/settings.json）：

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.tabSize": 2,
  "files.associations": {
    "*.vue": "vue"
  },
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "vue",
    "vue-html"
  ],
  "vetur.validation.template": false,
  "vetur.format.defaultFormatter.html": "js-beautify-html",
  "vetur.format.defaultFormatterOptions": {
    "js-beautify-html": {
      "wrap_attributes": "auto"
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 📦 Node.js 版本管理（nvm）

# 为什么使用 nvm？

  • ✅ 避免不同项目 Node 版本冲突
  • ✅ 快速切换 Node 版本
  • ✅ 支持多版本并存

# 安装 nvm

# macOS / Linux

# 使用官方安装脚本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# 重新加载配置
exec zsh  # 或 exec bash

# 验证安装
command -v nvm  # 输出 nvm 表示成功
1
2
3
4
5
6
7
8

# Windows

下载 nvm-windows (opens new window) 安装程序

# 使用 nvm

# 查看可安装的 Node 版本
nvm ls-remote

# 安装 Node 14（项目要求）
nvm install 14

# 使用 Node 14
nvm use 14

# 设置默认版本
nvm alias default 14

# 查看已安装版本
nvm ls

# 查看当前版本
node -v   # v14.x
npm -v    # 6.14.18
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 项目自动切换

项目根目录包含 .nvmrc 文件：

14
1

进入项目目录自动切换：

cd DarkM.UI
nvm use  # 自动使用 .nvmrc 指定的版本
1
2

# 🚀 安装依赖

# 首次安装

# 进入项目目录
cd DarkM.UI

# 确认 Node 版本
node -v   # 应为 v14.x
npm -v    # 应为 6.14+

# 安装依赖
npm install

# 或使用国内镜像加速
npm install --registry https://registry.npmmirror.com
1
2
3
4
5
6
7
8
9
10
11
12

# 安装问题排查

# 问题 1：权限错误

# 解决方案：修复 npm 权限
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
1
2
3
4
5

# 问题 2：依赖安装失败

# 清理缓存
npm cache clean --force

# 删除 node_modules
rm -rf node_modules package-lock.json

# 重新安装
npm install
1
2
3
4
5
6
7
8

# 问题 3：Sass 编译失败

# 安装 node-sass
npm install node-sass -D

# 或使用 dart-sass
npm install sass -D
1
2
3
4
5

# 💻 开发命令

# 常用命令

# 本地开发（热更新）
npm run serve

# 构建生产版本
npm run build

# 代码检查
npm run lint

# 修复代码格式
npm run lint -- --fix
1
2
3
4
5
6
7
8
9
10
11

# 维护命令

# 清理缓存
npm run cc        # 删除 .cache 目录

# 清理 node_modules
npm run cm        # 删除 node_modules 和 dist

# 构建并安装
npm run in        # build + install

# 构建并更新
npm run up        # build + update

# 发布到 NPM
npm run pub       # build + publish

# 发布到 UI 服务器
npm run pubtoui   # build + scp
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# package.json 脚本

{
  "scripts": {
    "serve": "vue-cli-service serve",
    "build": "vue-cli-service build",
    "lint": "vue-cli-service lint",
    "cm": "rimraf node_modules && rimraf dist",
    "cc": "rimraf node_modules/.cache",
    "in": "npm run build && npm install --registry http://npm.woowis.com",
    "up": "npm run build && npm update --registry http://npm.woowis.com",
    "pub": "npm run build && npm publish --registry http://npm.woowis.com",
    "pubtoui": "npm run build && scp -r dist/* woowis@pj.woowis.com:/home/woowis/runtime/web/darkm/ui"
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13

# ⚙️ 项目配置

# Vue.config.js

const path = require('path')

module.exports = {
  // 基本路径
  publicPath: './',
  
  // 输出目录
  outputDir: 'dist',
  
  // 静态资源目录
  assetsDir: 'static',
  
  // 是否使用运行时编译器
  runtimeCompiler: true,
  
  // 生产环境是否生成 source map
  productionSourceMap: false,
  
  // 开发服务器配置
  devServer: {
    port: 8080,
    open: true,
    proxy: {
      '/api': {
        target: 'http://localhost:6220',
        changeOrigin: true,
        pathRewrite: {
          '^/api': ''
        }
      }
    }
  },
  
  // CSS 相关配置
  css: {
    extract: true,
    requireModuleExtension: true,
    loaderOptions: {
      sass: {
        prependData: `@import "@/style/variables.scss";`
      }
    }
  },
  
  // Webpack 配置
  configureWebpack: {
    resolve: {
      alias: {
        '@': path.resolve(__dirname, './src'),
        'packages': path.resolve(__dirname, './packages')
      }
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

# .eslintrc.js

module.exports = {
  root: true,
  env: {
    node: true,
    browser: true
  },
  extends: [
    'plugin:vue/essential',
    'eslint:recommended',
    '@vue/prettier'
  ],
  parserOptions: {
    parser: 'babel-eslint'
  },
  rules: {
    'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    'no-debugger': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    'prettier/prettier': 'warn'
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# .prettierrc

{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": false,
  "singleQuote": true,
  "quoteProps": "as-needed",
  "jsxSingleQuote": false,
  "trailingComma": "none",
  "bracketSpacing": true,
  "jsxBracketSameLine": false,
  "arrowParens": "avoid",
  "endOfLine": "auto"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 🔧 常见问题

# 1. 更新包后运行不是最新效果？

原因： Node 缓存机制

解决：

# 清理缓存
npm run cc

# 或手动删除
rm -rf node_modules/.cache

# 重新启动
npm run serve
1
2
3
4
5
6
7
8

# 2. 热更新不生效？

解决：

# 检查 vue.config.js
# 确保没有禁用热更新

# 重启开发服务器
npm run serve
1
2
3
4
5

# 3. TypeScript 支持？

# 安装 TypeScript 依赖
npm install -D typescript @vue/cli-plugin-typescript

# 创建 tsconfig.json
npx tsc --init
1
2
3
4
5

# 4. 端口被占用？

解决：

# 修改 vue.config.js
devServer: {
  port: 8081  // 修改端口
}

# 或使用环境变量
PORT=8081 npm run serve
1
2
3
4
5
6
7

# 5. 代理配置不生效？

解决：

// 检查 vue.config.js 代理配置
devServer: {
  proxy: {
    '/api': {
      target: 'http://localhost:6220',
      changeOrigin: true,  // 必需
      pathRewrite: {
        '^/api': ''
      }
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12

# 📚 相关文档

# 🔗 参考链接

最后更新: 2022-08-07

← 核心框架 →