企业官网建设流程全解析

1. 从零到一：为什么我还在用最朴素的方式搭前端项目

每次带新人，总会被问到同一个问题：现在脚手架这么多，为什么还要手写一遍项目搭建？我的回答很直接——脚手架帮你省掉的是重复劳动，但省不掉你对项目结构的理解。一个前端项目从空文件夹到能跑起来，中间涉及包管理、构建工具、目录约定、开发服务器、接口联调这几件事，任何一环出问题，你都得知道去哪儿找。所以这篇内容我打算把"nodejs的前端项目搭建以及登陆接口开发"这件事拆开揉碎讲一遍，既适合刚接触全栈开发的朋友照着做，也适合已经能跑通但说不清原理的人回头补课。

这里说的"nodejs的前端项目"，指的是用Node.js作为运行环境和构建工具链的前端工程，而不是把Node当后端框架用。前端项目本身跑在浏览器里，但它的依赖安装、代码打包、开发服务器、接口代理，全都依赖Node生态。登录接口开发则是在同一个工程里加一个轻量的服务端，用来处理账号密码校验、会话维持这些逻辑。两者放在一起讲，是因为实际开发中前端和后端的边界往往就在一个项目目录里，分开讲反而割裂。

我见过太多人卡在第一步：npm install跑完不知道装了什么，npm run dev起来了不知道背后发生了什么，接口调不通就到处改配置。这篇内容会把这些黑盒一个个打开，让你不仅跑得起来，还说得清楚每一步在干什么。下面我会按真实开发顺序推进，从环境准备到项目骨架，再到登录接口的完整实现，最后聊几个我踩过的坑。

2. 环境准备：Node版本、包管理器与目录规划

2.1 Node版本的选择逻辑

Node的版本迭代很快，偶数版本是长期支持版，奇数版本是尝鲜版。做前端项目，我建议锁定偶数版本，比如18或20系列。原因很简单：前端构建工具链对Node版本有硬性要求，很多工具在奇数版本上会出现原生模块编译失败的问题。你可以用node -v查看当前版本，如果低于16，建议升级，因为Vite 5和Webpack 5的较新版本已经不再支持16以下。

版本管理我推荐用nvm这类工具，它允许你在同一台机器上装多个Node版本，按项目切换。比如老项目锁在16，新项目用20，一条命令就能切。安装nvm之后，nvm install 20装好，nvm use 20切换，nvm alias default 20设为默认。这样你就不用为了一个新项目把全局环境折腾一遍。

提示：切换Node版本后，之前装的全局包不会跟着走，需要在新版本下重新安装。这是很多人换版本后命令找不到的原因。

2.2 包管理器：npm、yarn还是pnpm

包管理器这件事没有绝对答案，但有几个判断维度。npm是Node自带的，零配置，但安装速度慢、磁盘占用大，因为每个项目的依赖都是独立复制一份。yarn早期解决了npm的速度和锁文件问题，但现在npm的差距已经很小。pnpm用硬链接和内容寻址存储，多个项目共享同一份依赖，磁盘占用最小，安装也最快，但它在某些老旧的构建工具上会有兼容性问题。

我的实际选择是：新项目一律pnpm，老项目维护继续用原来的。pnpm的node_modules结构是符号链接，这会让一些直接读取node_modules路径的工具出问题，但主流构建工具都已经适配。如果你团队里有人不熟悉pnpm，用npm也不会错，只是慢一点。

安装pnpm的方式是npm install -g pnpm，然后pnpm -v验证。之后所有npm install都可以换成pnpm install，命令基本兼容。

2.3 目录结构的前置规划

很多人拿到项目就开始写代码，写到一半发现文件到处放，改个接口地址要翻五个文件。我的习惯是在动手前先把目录定下来。一个典型的前端项目加登录接口，目录大概长这样：

project-root/ src/ 前端源码 api/ 接口请求封装 components/ 通用组件 pages/ 页面 utils/ 工具函数 App.jsx main.jsx server/ 服务端代码 routes/ 路由 controllers/ 业务逻辑 middleware/ 中间件 app.js 服务入口 public/ 静态资源 package.json vite.config.js

这个结构的好处是前后端代码在同一个仓库但物理隔离，前端构建产物不会混进服务端代码，服务端也不会被前端构建工具误处理。api目录单独抽出来，是为了让接口地址、请求拦截、错误处理集中管理，后面改baseURL只动一个文件。

3. 项目骨架搭建：从空文件夹到能跑起来的开发服务器

3.1 初始化与依赖安装

在空目录下执行pnpm init，会生成一个package.json。然后安装核心依赖。前端框架我选React，构建工具选Vite，理由是Vite的开发服务器启动快，热更新几乎无感，配置也简单。安装命令是：

pnpm add react react-dom pnpm add -D vite @vitejs/plugin-react

-D表示开发依赖，这些包只在开发和构建时用，不会打进最终产物。装完之后在package.json的scripts里加两条：

{ "scripts": { "dev": "vite", "build": "vite build" } }

pnpm dev启动开发服务器，默认端口5173。pnpm build打包生产版本，产物在dist目录。

3.2 Vite配置里最容易被忽略的两项

Vite的配置文件vite.config.js默认几乎不用改就能跑，但有两个配置我建议一开始就加上。第一个是server.proxy，用来解决开发时的跨域问题。前端跑在5173，后端接口跑在3000，浏览器直接请求会跨域。代理的写法是：

export default { server: { proxy: { '/api': { target: 'http://localhost:3000', changeOrigin: true } } } }

这样前端请求/api/login，Vite开发服务器会转发到http://localhost:3000/api/login，浏览器看到的是同源请求，跨域问题消失。changeOrigin的作用是把请求头里的host改成目标地址，某些后端框架会校验这个。

第二个是resolve.alias，给常用路径起别名。比如把src映射成@，这样不管文件嵌套多深，导入都用@/components/Button，不用写一堆../../。配置是：

import { resolve } from 'path' export default { resolve: { alias: { '@': resolve(__dirname, 'src') } } }

3.3 入口文件与最小可运行页面

创建index.html放在项目根目录，Vite默认以它为入口。内容里有一个<div id="root"></div>和一个指向/src/main.jsx的script标签。然后写main.jsx：

import React from 'react' import ReactDOM from 'react-dom/client' import App from './App' ReactDOM.createRoot(document.getElementById('root')).render( <React.StrictMode> <App /> </React.StrictMode> )

App.jsx先放一个最简单的组件，确认页面能渲染出来。这一步的意义是建立一个可验证的基线，后面加任何功能，出问题都能回退到这个能跑的状态。我见过有人一上来就装一堆库、写一堆配置，结果页面白屏，排查半天发现是某个配置写错了。先跑通最小闭环，再逐步加东西，是更稳的做法。

4. 登录接口开发：在同一个工程里写一个够用的服务端

4.1 为什么用Express而不是更重的框架

登录接口的逻辑其实很薄：接收账号密码、查库比对、返回结果、维持会话。用Express就够了，它轻、中间件生态成熟、上手快。NestJS这类框架适合大型项目，但对一个登录接口来说，配置成本太高。安装Express和几个必要的中间件：

pnpm add express cors body-parser jsonwebtoken bcryptjs

cors处理跨域，虽然开发时用Vite代理绕过了，但生产环境如果前后端分域部署还是需要。body-parser解析请求体，Express 4.16之后内置了express.json()，其实可以不装，但显式写出来更清楚。jsonwebtoken生成和校验令牌，bcryptjs做密码哈希。

4.2 服务端入口与中间件顺序

创建server/app.js：

const express = require('express') const cors = require('cors') const app = express() app.use(cors()) app.use(express.json()) app.use('/api', require('./routes/auth')) app.listen(3000, () => { console.log('server running on 3000') })

中间件的顺序很重要。cors必须在路由之前，否则预检请求会被路由拦截。express.json()也必须在处理请求体的路由之前，不然req.body是undefined。这个顺序问题我踩过，当时接口一直返回400，排查半天发现是json解析中间件写在了路由后面。

4.3 密码哈希：为什么不能明文存

密码存储的第一原则是永远不要明文存。原因是一旦数据库泄露，所有用户的密码直接暴露，而且很多人跨平台用同一个密码，影响面会扩大。哈希的作用是把密码变成不可逆的字符串，即使拿到哈希值也推不出原密码。

bcryptjs是bcrypt算法的纯JS实现，不需要编译原生模块，安装即用。它的特点是自带盐值，每次哈希同一个密码结果都不同，但校验时能正确匹配。用法：

const bcrypt = require('bcryptjs') const hash = await bcrypt.hash(password, 10) const match = await bcrypt.compare(inputPassword, hash)

第二个参数10是盐的轮数，数值越大越安全但越慢。10到12是常用范围，再高会影响登录响应速度。我一般用10，对普通应用足够。

4.4 JWT令牌的生成与校验

登录成功后，服务端需要给客户端一个凭证，后续请求带着它证明身份。JWT是常用方案，它把用户信息编码进令牌，服务端不用存session，适合前后端分离。生成令牌：

const jwt = require('jsonwebtoken') const token = jwt.sign( { userId: user.id }, process.env.JWT_SECRET, { expiresIn: '7d' } )

JWT_SECRET是签名密钥，必须放在环境变量里，不能写死在代码中。写死的话，代码一旦泄露，任何人都能伪造令牌。expiresIn设过期时间，7天是常见值，太长不安全，太短用户频繁登录。

校验令牌用中间件：

function auth(req, res, next) { const token = req.headers.authorization?.split(' ')[1] if (!token) return res.status(401).json({ message: '未登录' }) try { req.user = jwt.verify(token, process.env.JWT_SECRET) next() } catch { res.status(401).json({ message: '令牌无效' }) } }

authorization头的格式是Bearer <token>，所以用空格分割取第二部分。校验失败统一返回401，前端收到401就跳登录页。

4.5 登录路由的完整实现

把上面的东西串起来，server/routes/auth.js：

const express = require('express') const bcrypt = require('bcryptjs') const jwt = require('jsonwebtoken') const router = express.Router() const users = [] router.post('/register', async (req, res) => { const { username, password } = req.body if (users.find(u => u.username === username)) { return res.status(409).json({ message: '用户已存在' }) } const hash = await bcrypt.hash(password, 10) users.push({ id: users.length + 1, username, password: hash }) res.json({ message: '注册成功' }) }) router.post('/login', async (req, res) => { const { username, password } = req.body const user = users.find(u => u.username === username) if (!user) return res.status(401).json({ message: '账号或密码错误' }) const match = await bcrypt.compare(password, user.password) if (!match) return res.status(401).json({ message: '账号或密码错误' }) const token = jwt.sign({ userId: user.id }, process.env.JWT_SECRET, { expiresIn: '7d' }) res.json({ token, username: user.username }) }) module.exports = router

这里用内存数组模拟数据库，实际项目换成真实数据库即可，逻辑不变。注意登录失败时账号不存在和密码错误返回同样的提示，这是为了避免攻击者通过错误信息判断账号是否存在。

5. 前端对接登录接口：请求封装与状态管理

5.1 请求封装的必要性

直接在组件里写fetch或axios不是不行，但接口地址散落各处，改一个baseURL要全局搜索替换，加统一错误处理也无处下手。封装一层的好处是集中管理。我用axios，先装pnpm add axios，然后建src/api/request.js：

import axios from 'axios' const request = axios.create({ baseURL: '/api', timeout: 10000 }) request.interceptors.request.use(config => { const token = localStorage.getItem('token') if (token) config.headers.Authorization = `Bearer ${token}` return config }) request.interceptors.response.use( res => res.data, err => { if (err.response?.status === 401) { localStorage.removeItem('token') window.location.href = '/login' } return Promise.reject(err) } ) export default request

请求拦截器自动带令牌，响应拦截器统一处理401。这样业务代码里不用关心令牌怎么带、401怎么跳，只关注数据本身。

5.2 登录页面的交互细节

登录表单看起来简单，但有几个细节容易忽略。第一是提交时禁用按钮，防止重复点击造成多次请求。第二是错误提示要具体，但不要泄露账号是否存在。第三是登录成功后令牌存哪里。localStorage简单但有XSS风险，httpOnly cookie更安全但需要服务端配合设置。普通项目用localStorage够用，安全要求高的场景建议用cookie。

一个简化的登录组件逻辑：

const [loading, setLoading] = useState(false) const [error, setError] = useState('') async function handleSubmit(e) { e.preventDefault() setLoading(true) setError('') try { const data = await request.post('/login', { username, password }) localStorage.setItem('token', data.token) navigate('/dashboard') } catch (err) { setError(err.response?.data?.message || '登录失败') } finally { setLoading(false) } }

finally里重置loading，保证无论成功失败按钮都能恢复。这个细节很多人漏掉，导致请求失败后按钮一直转圈。

5.3 路由守卫与登录态判断

未登录用户不应该能访问需要权限的页面。路由守卫的思路是在进入路由前检查令牌是否存在，不存在就重定向到登录页。React Router里可以用一个包装组件：

function RequireAuth({ children }) { const token = localStorage.getItem('token') if (!token) return <Navigate to="/login" replace /> return children }

replace的作用是替换历史记录，这样用户点后退不会回到需要权限的页面。令牌是否有效最终由服务端校验，前端只做初步拦截，不能作为安全依据。

6. 联调阶段最容易踩的五个坑

6.1 跨域问题的两种表现

跨域有两种情况：简单请求和预检请求。简单请求浏览器直接发，服务端返回的响应头里没有Access-Control-Allow-Origin就报错。预检请求是浏览器先发一个OPTIONS请求问服务端允不允许，允许了才发真实请求。很多人只配了Access-Control-Allow-Origin，没处理OPTIONS，导致带自定义头的请求失败。用cors中间件的话它会自动处理OPTIONS，手写的话要记得加。

开发阶段用Vite代理是最省事的方案，生产环境如果前后端同域部署，代理配置直接搬到Nginx即可。

6.2 令牌过期后的用户体验

令牌设了7天过期，用户第8天打开页面，请求全部401，如果直接跳登录页，用户正在填的表单就丢了。更好的做法是拦截401后先尝试刷新令牌，刷新失败再跳登录。刷新令牌需要服务端提供一个/refresh接口，用长期有效的refresh token换新的access token。这套机制稍复杂，但用户体验好很多。简单项目可以先不做，但要知道这个方向。

6.3 密码传输的安全边界

前端到服务端的密码传输，如果是HTTP明文，中间任何节点都能截获。生产环境必须上HTTPS。前端可以对密码做一次哈希再传，但这只是增加一点成本，不能替代HTTPS，因为哈希值本身也能被重放。真正的安全靠HTTPS加服务端哈希存储加登录频率限制。

6.4 环境变量的管理

JWT_SECRET、数据库连接串这些不能写进代码。用.env文件管理，配合dotenv加载。.env要加进.gitignore，不能提交到仓库。团队协作时提供一个.env.example，列出需要哪些变量但不含真实值。我见过有人把密钥提交到公开仓库，结果被人扫到滥用，这个教训很深刻。

6.5 构建产物与接口地址的分离

开发时用代理，生产时前端静态文件和后端接口可能在不同域名。这时候baseURL不能写死/api，要根据环境切换。Vite支持用import.meta.env.MODE判断，或者用.env.production文件配不同的值。构建时Vite会把对应的值注入代码。这个机制要在项目初期就配好，后期改会牵动很多文件。

7. 我在这类项目里积累的几条实操心得

第一条是关于依赖版本的。前端生态更新快，但不要盲目追新。大版本升级往往有破坏性变更，比如Vite从4到5、React从17到18，都有需要改代码的地方。我的做法是锁版本，package.json里不用^，用精确版本，升级时手动改并跑一遍测试。这样避免某天pnpm install之后项目突然跑不起来。

第二条是关于接口设计的。登录接口的返回结构要统一，成功返回{ token, username }，失败返回{ message }，前端拦截器按这个约定处理。不要一会儿返回字符串一会儿返回对象，前端处理起来很痛苦。错误码也要统一，401表示未登录或令牌无效，403表示无权限，409表示资源冲突，这些约定俗成的东西遵守就好，不要自创。

第三条是关于调试的。接口调不通时，先看Network面板的请求有没有发出去，发出去了看请求头和请求体对不对，再看响应状态码和响应体。这三步能定位大部分问题。如果请求根本没发出去，检查前端代码；发出去了但服务端没收到，检查代理配置；服务端收到了但返回错误，看服务端日志。按这个顺序排查，比到处改配置高效得多。

第四条是关于代码组织的。登录相关的逻辑，服务端集中在routes/auth.js，前端集中在api/auth.js和登录组件里，不要散落。这样以后要加第三方登录、短信登录，改动范围可控。我见过登录逻辑散在五六个文件里的项目，加一个验证码功能要改一圈，维护成本很高。

最后说一个心态上的事。搭建项目和写登录接口，技术上都不复杂，但它是理解前后端协作的最好切入点。把这一套跑通，再去学数据库、缓存、消息队列，都是在同样的框架上加东西。所以不要觉得简单就跳过，认真走一遍，把每个环节的原理搞清楚，后面学什么都会快很多。