Next.js + TypeScript + Tailwind + shadcn/ui 学习安装笔记

技术栈介绍

环境准备

node --version    # v24.3.0
npm --version     # 11.4.2
pnpm --version    # 9.13.2

安装 pnpm

npm install -g pnpm

一、安装 Next.js + TypeScript + Tailwind

1. 创建项目

npx create-next-app@latest nextjs-learn \
  --typescript \
  --tailwind \
  --eslint \
  --app \
  --src-dir \
  --import-alias "@/*" \
  --use-npm \
  --yes

参数说明：

2. 安装依赖

next
react
react-dom

devDependencies:
@tailwindcss/postcss
@types/node
@types/react
@types/react-dom
eslint
eslint-config-next
tailwindcss
typescript

3. 目录结构

src/
├─ app/           # App Router 页面
├─ components/    # React 组件
└─ lib/          # 工具函数

二、安装 shadcn/ui

1. 初始化

npx shadcn@latest init -y --defaults

这会：

• 创建 components.json 配置文件
• 更新 tailwind.config.ts
• 更新 src/app/globals.css
• 安装基础依赖

2. 添加组件

npx shadcn@latest add card badge input --yes

常用组件：

3. 组件结构

src/components/ui/
├─ button.tsx
├─ card.tsx
├─ badge.tsx
└─ input.tsx

三、配置文件

components.json

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "src/app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  }
}

lib/utils.ts

import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

四、使用示例

Button

import { Button } from "@/components/ui/button"

export default function Demo() {
  return <Button>Click me</Button>
}

Card

import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"

export function DemoCard() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Title</CardTitle>
      </CardHeader>
      <CardContent>
        Content here
      </CardContent>
    </Card>
  )
}

五、Tailwind CSS 基础

常用类

<!-- 布局 -->
<div class="flex items-center justify-between">

<!-- 间距 -->
<p class="m-4 p-4">

<!-- 颜色 -->
<button class="bg-primary text-white">

<!-- 响应式 -->
<div class="hidden md:block">

配置主题

在 tailwind.config.ts 中自定义：

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: "#xxx"
      }
    }
  }
}

六、常用命令

# 开发
npm run dev

# 构建
npm run build

# 生产
npm run start

# lint
npm run lint

七、常见问题

Q: shadcn/ui 和 Tailwind 版本兼容？

A: shadcn/ui 需要 Tailwind CSS v4，当前通过 @tailwindcss/postcss 集成。

Q: 如何升级 shadcn？

npx shadcn@latest upgrade

Q: 组件样式不生效？

检查 globals.css 是否包含：

@tailwind base;
@tailwind components;
@tailwind utilities;