企业官网建设流程全解析

1. 为什么选择VSCode开发uni-app小程序

接触uni-app的开发者基本都绕不开HBuilderX，毕竟DCloud官方主推的就是它，新建项目、一键运行、打包发行确实方便。但很多人在团队协作、代码规范、插件生态这几块被HBuilderX憋得难受，这时候把开发环境切到VSCode是大势所趋。

先说下我自己的情况：从2020年开始用uni-app做小程序，前两年老老实实用HBuilderX，直到接手一个需要和前端团队共享代码库的项目——同事都用VSCode，就你打开的是HBuilderX，代码格式、提交规范、git可视化操作全对不上，沟通成本直线飙升。后来花了一周左右把整套VSCode开发uni-app的环境跑顺，现在再也不想切回HBuilderX写代码了。

用VSCode开发uni-app，核心思路是：写代码用VSCode，编译运行靠HBuilderX的CLI能力或者uni-app官方提供的命令行工具。说白了就是把编辑器和编译器解耦，各干各的。编辑器负责代码提示、格式化、git操作、代码检查，编译器负责打包和调试。

这套方案能解决几个实际问题：

• 代码提示和补全比HBuilderX舒服太多，特别写JavaScript和CSS的时候
• 团队协作没有工具壁垒，前端同学进来就能上手
• 插件生态丰富，ESLint、Prettier、GitLens、Todo Tree这些都是VSCode的强项
• VSCode本身的UI和交互习惯了以后，再也不想回去

当然也不是说HBuilderX一无是处，它毕竟深度整合了uni-app的编译流程，在某些场景下确实更省心。我的建议是：调试和看效果用HBuilderX，写代码用VSCode，两个工具配合着来，效率最高。下面我会把整个环境搭建和开发流程完整地拆开讲一遍。

2. 环境准备：从零搭建VSCode + uni-app开发环境

2.1 需要用到的工具清单

在开始之前，先把需要的工具列清楚：

这里有个关键点要提前说清楚：很多人以为用VSCode开发，就可以完全不装HBuilderX了。这是不对的。因为uni-app项目如果要运行到微信小程序，最终还是要调用微信开发者工具的预览接口，而HBuilderX在编译打包这个环节处理得最稳。所以HBuilderX还是要装，但它的定位变成了"编译引擎"，不再是"代码编辑器"。

2.2 Node.js安装与版本管理

如果还没装Node.js，建议直接去官网下载LTS版本。注意一件事：别图省事下载最新版，有些uni-app插件对Node版本有要求，太新的版本反而容易出兼容性问题。我实测下来Node 16和18都挺稳，20也没遇到大坑，但如果你用的是老项目，最好先确认package.json里的engines字段。

装完Node后，打开终端输入node -v和npm -v确认版本号能正常输出。如果提示找不到命令，多半是环境变量没配好，Windows用户检查一下系统环境变量里的Path有没有把Node的安装目录加进去。

2.3 VSCode安装和必要插件

VSCode的安装没什么好说的，一路下一步就行。装完之后先别急着写代码，把下面这些插件装上：

• Vue Language Features (Volar)：Vue 3语法支持，uni-app现在基本都是Vue 3语法了
• Vetur：如果还在用Vue 2的老项目，需要装这个
• ESLint：代码规范检查
• Prettier - Code formatter：统一代码风格
• uni-app-schemas：uni-app根目录配置文件的语法提示，比如pages.json和manifest.json
• uni-app：搜uniapp能找到的官方插件，提供一些代码片段
• GitLens：查看git提交记录和代码作者

装完插件之后，记得在VSCode的设置里把"Default Formatter"设为Prettier，同时开启"Format On Save"，这样每次保存代码都会自动格式化，团队协作的时候格式问题基本能杜绝。

2.4 微信开发者工具的配置

微信开发者工具装好之后，需要做一步关键配置：开启服务端口。打开微信开发者工具，进入设置 → 安全设置，把"服务端口"开关打开。这一步不操作的话，后面HBuilderX编译完没法自动唤起微信开发者工具预览。

另外建议在微信开发者工具的通用设置里，把"打开时默认显示代码"关掉，不然每次刷新项目都会弹出一堆页面，挡住调试窗口。

3. 两种主流开发模式的选型对比

3.1 HBuilderX项目模式：直接导入VSCode

这个模式最省事：在HBuilderX里创建好uni-app项目，然后用VSCode直接打开这个项目文件夹。代码全在VSCode里写，要编译运行的时候切回HBuilderX点一下"运行到小程序模拟器"。

好处是门槛低，用HBuilderX创建项目的时候他自动帮你把模板和依赖都配好了，不需要自己敲命令。坏处是两边来回切换比较烦，特别是要频繁改代码调试的时候。另外HBuilderX项目里的有些配置（比如sass依赖）在VSCode里看的时候会自动装依赖，有时候会莫名其妙多出一堆node_modules，这个属于正常现象。

这个模式适合：刚接触uni-app、不想折腾CLI、项目本身不大、不需要命令行操作打包流程的开发者。

3.2 CLI项目模式：VSCode全流程开发

这个模式就是官方推荐的uni-app CLI方式。用命令行创建项目，VSCode里装好依赖直接开发，编译运行用npm命令执行。整体流程是：

# 创建基于Vue 3的uni-app项目 npx degit dcloudio/uni-preset-vue#vite my-vue3-project # 进入项目目录 cd my-vue3-project # 安装依赖 npm install

装完之后项目结构比HBuilderX模式清晰很多，vue3+vite的目录布局，用VSCode打开之后各种提示和跳转都正常。运行的时候执行：

npm run dev:mp-weixin

编译完之后，产物在dist/dev/mp-weixin目录下，用微信开发者工具打开这个目录就能预览调试了。

CLI模式的好处是全流程不离开VSCode，代码提示、类型检查、git操作、终端命令全在一个工具里完成。坏处是首次配置比HBuilderX麻烦一些，微信开发者工具里的自动唤起也少了一步（每次都要手动打开dist目录，不太优雅）。

如果让我推荐，新项目优先选CLI模式，Vue 3大势所趋，而且坑基本都被踩完了，用起来比想象中顺手。

3.3 两种模式优缺点速查

4. 核心配置解析：pages.json与manifest.json

4.1 pages.json：页面与导航的配置中心

pages.json是uni-app项目的核心配置文件之一，类似小程序原生的app.json，负责管理页面路由、窗口样式、导航栏效果、tabBar，还有权限申请等。

在VSCode里写pages.json的时候，装了uni-app-schemas插件就能获得完整的属性提示和校验。一个常见的配置片段长这样：

{ "pages": [ { "path": "pages/index/index", "style": { "navigationBarTitleText": "首页", "navigationBarBackgroundColor": "#ffffff", "navigationBarTextStyle": "black" } }, { "path": "pages/my/my", "style": { "navigationBarTitleText": "个人中心", "enablePullDownRefresh": true } } ], "globalStyle": { "navigationBarTextStyle": "black", "navigationBarTitleText": "我的小程序", "navigationBarBackgroundColor": "#F8F8F8", "backgroundColor": "#F8F8F8" }, "tabBar": { "color": "#7A7E83", "selectedColor": "#007AFF", "borderStyle": "black", "backgroundColor": "#ffffff", "list": [ { "pagePath": "pages/index/index", "text": "首页" }, { "pagePath": "pages/my/my", "text": "我的" } ] } }

pages数组里注册的页面路径对应你项目的pages目录下的vue文件。有个经常踩的坑是路径大小写问题，在Windows上开发可能没问题，但一旦部署到云端打包或者用Mac的同事打开，大小写不一致就会报找不到页面的错。我的习惯是所有页面路径统一用小写字母命名。

4.2 manifest.json：src目录下的应用配置

在CLI项目模式里，manifest.json放在src目录下，和pages.json平级。这个文件配置的是应用相关信息，比如应用名称、appid、小程序相关设置、vue版本等。

微信小程序的appid要在这里填，从微信公众平台申请的小程序appid拷过来。

{ "name": "my-vue3-project", "appid": "", "description": "", "versionName": "1.0.0", "versionCode": "100", "transformPx": false, "app-plus": { "usingComponents": true, "nvueStyleCompiler": "uni-app", "compilerVersion": 3 }, "mp-weixin": { "appid": "你的小程序appid", "setting": { "urlCheck": false, "es6": true, "minified": true }, "usingComponents": true } }

在开发调试阶段，推荐把urlCheck设为false，否则调接口的时候域名不是https或者没在小程序后台配置白名单，就会一直报request请求失败。

4.3 VSCode工作区设置推荐

把项目在VSCode里打开之后，在项目根目录创建.vscode/settings.json文件，写入下面的配置，可以避免很多格式和保存问题：

{ "files.eol": "\n", "editor.tabSize": 2, "editor.formatOnSave": true, "editor.defaultFormatter": "esbenp.prettier-vscode", "editor.codeActionsOnSave": { "source.fixAll.eslint": true }, "eslint.validate": [ "javascript", "javascriptreact", "vue" ], "vetur.validation.template": true, "prettier.semi": false, "prettier.singleQuote": true }

特别要提一下"files.eol": "\n"这个配置。Windows下默认的行尾符是CRLF，Mac和Linux下是LF，如果团队里有不同操作系统的人，git提交的时候会因为行尾符不一致产生大量diff，看着特别糟心。统一用LF能省掉很多麻烦。

5. 编译运行与调试：打通VSCode到微信开发者工具的链路

5.1 CLI项目的编译运行流程

以Vue 3 CLI项目为例，执行npm run dev:mp-weixin之后，Vite会启动开发模式，对src目录进行编译打包，把结果输出到dist/dev/mp-weixin目录。首次编译可能要等一会，因为要装依赖、搞预构建，后面基本就快了，通常在3到5秒内完成增量编译。

编译完成后，微信开发者工具里导入项目，目录选择dist/dev/mp-weixin。这样改代码保存后，VSCode终端会实时编译，微信开发者工具会自动刷新页面，开发调试体验和HBuilderX模式差不了太多。

有个小技巧：可以在VSCode里配置一个快捷键或者任务，一键启动编译。在.vscode/tasks.json里加个任务：

{ "version": "2.0.0", "tasks": [ { "label": "dev:mp-weixin", "type": "shell", "command": "npm run dev:mp-weixin", "problemMatcher": [], "presentation": { "reveal": "always", "panel": "new" } "group": { "kind": "build", "isDefault": true } } ] }

然后按Ctrl+Shift+B就能启动编译任务，不用每次去终端敲命令。

5.2 微信开发者工具调试要点

小程序编译出来之后，微信开发者工具里的调试能力其实还挺全的，Wxml面板可以查看页面结构，Sources面板可以打断点调试js，Network面板看接口请求。但要注意一个问题：dev模式编译出来的代码做了source-map映射，小程序工具里看到的文件路径和源码路径是对应的，所以打断点的时候要选src目录下的vue文件。

接口调试的话，建议在微信开发者工具的控制台里多利用System Log和WXML面板。还有个经常被忽略的功能：在"调试器"的Console标签页里，可以直接使用getCurrentPages()方法查看当前页面栈，定位页面跳转问题很方便。

5.3 HBuilderX项目如何接入VSCode调试

如果你用的是HBuilderX创建的项目，又想用VSCode写代码，那么调试流程就是：在VSCode里改代码 → 切到HBuilderX点击运行 → 微信开发者工具自动打开。这个模式代码是"JIT编译"的，每次保存后HBuilderX检测到文件变化就会自动编译，然后微信开发者工具右上角手动点一下"编译"按钮刷新。

有一点要注意，HBuilderX的项目在VSCode里打开后，第一次会自动安装依赖，可能会弹出npm install的提示，等它装完就好。别用VSCode的终端手动删node_modules，容易把HBuilderX的软链搞出问题。

6. 常见问题与排查技巧实录

6.1 编译器版本不一致导致页面空白

这是用VSCode开发uni-app最常见的坑之一。表现是：VSCode里写好的代码，在HBuilderX里运行没问题，但用CLI方式编译后小程序页面空白。

排查思路：先看控制台有没有报错，然后确认CLI项目里的uni-app依赖版本和HBuilderX内置的编译器版本是否一致。因为CLI项目的依赖版本来源于package.json，如果安装的时候用了通配符^或者~，有可能拉到新版本，而新版本和HBuilderX的编译器不配套。解决办法就是锁版本，把依赖版本号精确到具体数字，比如"@dcloudio/vite-plugin-uni": "3.0.0-3081220230802001"，然后重新装依赖。

6.2 vscode终端npm命令识别不了

Windows用户比较常见，VSCode打开的终端是PowerShell，但npm的全局路径没加进系统环境变量。解决办法：在系统环境变量里找到Path，把npm的全局node_modules路径加进去，或者直接在项目里用npx命令代替npm，比如：

npx npm run dev:mp-weixin

6.3 修改页面后微信开发者工具不刷新

CLI模式下，改了代码VSCode终端提示编译完成，但微信开发者工具没反应。这个大概率是小程序工具的"热重载"被关了。在微信开发者工具的右上角"详情"里，勾选"启用热重载"，同时确认"不校验合法域名"也勾上了。

还有一种情况是微信开发者工具打开了多个项目窗口，dev编译刷新的是最新打开的那个。注意看工具窗口顶部的项目路径，是不是指向了正确的dist目录。

6.4 sass/scss样式出错

CLI项目如果用了sass，需要额外安装：

npm install sass sass-loader -D

注意sass-loader的版本和这个项目使用的编译器要匹配。Vue 3 + Vite项目建议用sass-loader 13以上版本。装完后记得重启编译，不然样式不生效。

6.5 引用本地图片不显示

CLI项目中图片路径不能用相对路径随便指，最好统一放在src/static目录下，用/static/xxx.png这种方式引用。因为小程序打包后图片资源会被重新处理，相对路径在有些层级情况下会找不到。HBuilderX项目相对宽松，但CLI项目必须按这个规范来。

6.6 调试时页面跳转报错找不到页面

大多数时候是pages.json里少注册了页面，或者注册的路径和实际文件路径不一致。在VSCode里改完页面文件之后，记得检查pages.json的pages数组里有没有加对应条目。如果想省事，可以直接用uni-ui的页面创建工具，它会自动同步注册。

6.7 常见问题速查表

7. 实战配置建议与我的个人体会

整套环境跑顺之后，我个人的实际体验是：VSCode写代码这部分的舒适度和生产力，确实比HBuilderX高出不少。尤其是ESLint和Prettier的组合，代码提交的时候git diff干干净净，代码review也不用废话。

如果你打算长期用这套方案，在项目初始化阶段就把下面几件事做好：

1. 开启ESLint检查：CLI项目模板默认带了eslint配置，别删，往里加规则就好
2. 配置Prettier和ESLint协作：Prettier负责格式，ESLint负责规范，两个别冲突
3. gitignore要完善：dist目录、node_modules、unpackage这种编译产物和依赖目录必须ignore
4. 创建好模板页面：新建页面的时候直接粘贴模板改改，省事且规范

# 最后贴一个我常用的页面模板，新建页面的时候复制一份改改就能用 <template> <view class="container"> <text>{{ title }}</text> </view> </template> <script setup> import { ref } from 'vue' const title = ref('新的页面') </script> <style scoped> .container { padding: 30rpx; } </style>

还有一个经验：CLI项目的dist目录生成规则和HBuilderX不一样，HBuilderX是unpackage/dist，CLI是dist/dev和dist/build。如果你要接CI/CD自动化打包，一定要先搞清楚你用的项目类型，不然脚本路径写错一跑就挂。

在用这套方案的这段时间里，我踩过最深的坑就是依赖版本问题，某次升级了@dcloudio相关的依赖，结果编译出来的小程序在iOS上白屏，Android正常，排查了整整一天才定位到是编译器版本和微信基础库不兼容。从那以后，所有uni-app相关依赖我全部锁死版本号，除非明确要升级，否则一行都不动。

如果你在配置过程中遇到编译链路的问题，我的建议是先去看VSCode终端里的完整报错信息，不要只看微信开发者工具里的提示。因为整个链路里，VSCode终端报的是编译引擎的错误，微信开发者工具报的是运行时的DOM或JS错误，两个层面不一样，先分清是哪一层出问题，排查效率能高一倍。

另外，把一次完整的开发调试流程放再这里给你参考：

1. 打开VSCode，启动编译任务（Ctrl+Shift+B）
2. 编译完成后，打开微信开发者工具，导入dist/dev/mp-weixin目录
3. 在VSCode里改代码，保存，等待终端显示编译完成
4. 切到微信开发者工具，看效果，调试接口
5. 需要打包上线的，执行npm run build:mp-weixin，产物在dist/build/mp-weixin目录
6. 微信开发者工具里上传代码，提交审核

这套流程我跑了一年多，除了偶尔微信基础库升级会有告警，其他都很稳定。希望这篇文章能把你在VSCode和uni-app之间打通的路给铺清楚，省下当初我踩坑的那些时间。