{ "version": "https://jsonfeed.org/version/1", "title": "老王", "home_page_url": "https://老王.me/blog", "description": "feedId:41215011978385457+userId:41840354283324416", "items": [ { "id": "https://老王.me/blog/ts-tutorial", "content_html": "

本教程面向零基础或刚接触 TypeScript 的开发者，按由浅入深的顺序讲解所有主要知识点。建议按章节顺序阅读。

\n
\n

一、TypeScript 简介​

\n

什么是 TypeScript？​

\n

TypeScript 是 JavaScript 的超集，核心是为代码增加 静态类型。它能在你运行之前就发现很多类型错误，从而提升代码可靠性与可维护性。

\n

为什么需要 TypeScript？​

\n\n
\n

二、环境与安装​

\n

安装 TypeScript​

\n

在项目目录中初始化：

\n
mkdir my-ts-app
cd my-ts-app
npm init -y
\n

安装 TypeScript：

\n
npm i -D typescript
npx tsc --version
\n

初始化 tsconfig.json​

\n
npx tsc --init
\n

tsconfig.json 用于配置编译选项（如 target、module、是否开启严格模式等）。

\n
\n

三、类型系统入门​

\n

基本类型​

\n
let name: string = 'Alice'
let age: number = 18
let isOk: boolean = true
let nothing: null = null
let undef: undefined = undefined

let anyValue: any = 123
let unknownValue: unknown = 'text'
\n

其中：

\n\n

联合类型与类型收窄​

\n
function formatId(id: number | string) {
  if (typeof id === 'number') return `#${id.toFixed(0)}`
  return `#${id}`
}
\n
\n

四、接口与类型别名​

\n

接口（interface）​

\n
interface User {
  id: string
  name: string
  email?: string
}
\n

类型别名（type）​

\n
type Point = {
  x: number
  y: number
}
\n

它们都能描述对象结构，实际项目中可以按团队习惯选择使用。

\n
\n

五、泛型与高级类型​

\n

泛型函数​

\n
function wrap<T>(value: T) {
  return { value }
}

const res = wrap(123) // T = number
\n

工具类型（内置）​

\n

常见工具类型：

\n
type PartialUser = Partial<User>
type ReadonlyUser = Readonly<User>
type PickUser = Pick<User, 'id' | 'name'>
type RecordMap = Record<string, number>
\n
\n

六、类与模块​

\n

类（class）​

\n
class Person {
  constructor(public name: string) {}

  sayHello() {
    return `hello, ${this.name}`
  }
}
\n

模块（import / export）​

\n

src/user.ts：

\n
export interface User {
  id: string
  name: string
}
\n

src/main.ts：

\n
import type { User } from './user'

const u: User = { id: '1', name: 'Alice' }
console.log(u)
\n
\n

七、编译与 tsconfig​

\n

基本编译命令​

\n
npx tsc
\n

常用的方式是在 package.json 配置脚本：

\n
{
  \"scripts\": {
    \"build\": \"tsc -p tsconfig.json\"
  }
}
\n

严格模式（建议逐步开启）​

\n

tsconfig.json 中常见选项：

\n\n

新手建议不要一口气全开，但可以从最基础的开始。

\n
\n

八、与 Node.js 结合：Express 示例（TS）​

\n

安装依赖​

\n
npm i express
npm i -D @types/express ts-node nodemon
\n

创建 src/server.ts：

\n
import express from 'express'

const app = express()
app.use(express.json())

app.get('/health', (_req, res) => {
  res.json({ ok: true })
})

app.post('/echo', (req, res) => {
  res.json({ received: req.body })
})

app.listen(3000, () => {
  console.log('server running at http://localhost:3000')
})
\n

启动（开发模式）：

\n
nodemon --exec ts-node src/server.ts
\n
\n

九、常见工程化：lint/format​

\n

工程化不是“越多越好”，但至少应做到：

\n\n

你可以先从 prettier 开始，后续再加 ESLint。

\n
\n

十、测试与构建​

\n

测试思路​

\n

常用方案：

\n\n

这里建议你先跑通：

\n
    \n
  1. 把业务逻辑从路由中抽离成函数
    2. \n
  2. 对函数进行单测
    3. \n
\n
\n

十一、最佳实践与小结​

\n

最佳实践​

\n\n

小结​

\n\n
\n

十二、学习路径小结​

\n
    \n
  1. 跑通 tsc 编译流程，理解输出与模块形式
    2. \n
  2. 掌握基础类型、联合类型与类型收窄
    3. \n
  3. 学会接口、泛型与常见工具类型
    4. \n
  4. 结合 Express 写一个最小 API
    5. \n
  5. 从抽离业务逻辑开始加测试，逐步形成工程习惯
    6. \n
\n

遇到问题可查阅 TypeScript 官方文档。

", "url": "https://老王.me/blog/ts-tutorial", "title": "TypeScript 完整教程（新手向）", "summary": "由浅入深学习 TypeScript，覆盖类型系统、接口与泛型、工程化（tsconfig/构建）、与 Node.js 结合开发 API 等主要知识点。", "date_modified": "2026-03-19T15:11:56.000Z", "tags": [] }, { "id": "https://老王.me/blog/nextjs-tutorial", "content_html": "

本教程面向零基础或刚接触 Next.js 的开发者，按由浅入深的顺序讲解所有主要知识点。建议按章节顺序阅读。

\n
\n

一、Next.js 简介​

\n

什么是 Next.js？​

\n

Next.js 是一个基于 React 的 Web 框架，提供了路由、渲染与构建能力，让你更容易构建：

\n\n

适合做什么？​

\n\n
\n

二、环境准备与创建项目​

\n

环境要求​

\n\n

创建项目​

\n

使用官方推荐的脚手架 create-next-app：

\n
npx create-next-app@latest my-next-app
\n

初始化安装完成后进入目录并启动：

\n
cd my-next-app
npm run dev
\n

浏览器打开 http://localhost:3000 即可。

\n
新手提示

如果你在 WSL / 远程环境访问开发服务器，可能需要让 Next.js 监听所有网卡（或通过端口转发访问）。

\n
\n

三、App Router（推荐）与基础目录结构​

\n

Next.js（新版本）通常使用 App Router。常见目录结构如下：

\n
my-next-app/
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   └── api/
│       └── health/route.ts
├── public/
├── src/ (可选：把组件/业务逻辑放这里)
├── package.json
└── next.config.js
\n

关键约定：

\n\n
\n

四、路由与页面（Page / Layout）​

\n

页面：page.tsx​

\n

创建一个路由 app/about/page.tsx：

\n
// app/about/page.tsx
export default function AboutPage() {
  return (
    <main>
      <h1>About</h1>
      <p>这是一个 /about 页面。</p>
    </main>
  )
}
\n

链接：Link​

\n

使用 Next.js 的 Link 进行跳转（推荐）：

\n
import Link from 'next/link'

export default function Home() {
  return (
    <main>
      <h1>Home</h1>
      <Link href=\"/about\">去 About</Link>
    </main>
  )
}
\n
\n

五、组件与样式（CSS Modules / 全局样式）​

\n

CSS Modules​

\n

假设你有 app/components/Hello.module.css：

\n
.title {
  color: #2e8555;
}
\n

然后在组件中使用：

\n
import styles from './Hello.module.css'

export default function Hello() {
  return <h1 className={styles.title}>Hello Next.js</h1>
}
\n

全局样式​

\n

通常在 app/globals.css 引入全站样式，并在根布局 layout.tsx 中导入。

\n
\n

六、数据获取（Data Fetching）​

\n

在 App Router 下，你常见会遇到几种数据获取方式：

\n
    \n
  1. Server Components 里直接 fetch（最常见的新手路径）
    2. \n
  2. 使用 Route Handler 提供 API，再在客户端请求
    3. \n
  3. 需要更复杂缓存策略时，显式配置 Next.js 的缓存行为
    4. \n
\n

服务端 fetch 示例​

\n

app/posts/page.tsx：

\n
export default async function PostsPage() {
  const res = await fetch('https://jsonplaceholder.typicode.com/posts', {
    // 新手先用默认策略即可；需要时再研究缓存/重验证
    cache: 'no-store',
  })
  const posts = await res.json()

  return (
    <main>
      <h1>Posts</h1>
      <ul>
        {posts.slice(0, 5).map((p: any) => (
          <li key={p.id}>{p.title}</li>
        ))}
      </ul>
    </main>
  )
}
\n
\n

七、Route Handler（类似 API 路由）​

\n

在 App Router 中，你可以在 app/api/.../route.ts 里写接口。

\n

例如 app/api/health/route.ts：

\n
import { NextResponse } from 'next/server'

export async function GET() {
  return NextResponse.json({ ok: true })
}
\n

访问：/api/health

\n

你也可以扩展为 POST / PUT / DELETE 等方法。

\n
\n

八、构建与部署​

\n

构建​

\n
npm run build
\n

本地预览​

\n
npm run start
\n
\n

部署到 Vercel（新手最省事）​

\n

Next.js 官方在 Vercel 上体验最佳。一般步骤：

\n\n
\n

九、常见问题与小结​

\n

常见问题​

\n\n

小结​

\n\n
\n

十、学习路径小结​

\n
    \n
  1. 新建 Next.js 项目并跑通 npm run dev
    2. \n
  2. 写 layout.tsx 和一个 about/page.tsx
    3. \n
  3. 用 Link 做页面跳转
    4. \n
  4. 写一个 fetch 示例页面并观察加载行为
    5. \n
  5. 写 app/api/health/route.ts 测试接口
    6. \n
  6. 完成 npm run build 与本地 npm run start 预览
    7. \n
\n

遇到问题可查阅 Next.js 官方文档。

", "url": "https://老王.me/blog/nextjs-tutorial", "title": "Next.js 完整教程（新手向）", "summary": "由浅入深学习 Next.js，覆盖 App Router、路由、数据获取、组件与样式、Route Handler、部署与常见问题等主要知识点。", "date_modified": "2026-03-19T15:11:56.000Z", "tags": [] }, { "id": "https://老王.me/blog/nestjs-tutorial", "content_html": "

本教程面向零基础或刚接触 NestJS 的开发者，按由浅入深的顺序讲解所有主要知识点。建议按章节顺序阅读。

\n
\n

一、NestJS 简介​

\n

什么是 NestJS？​

\n

NestJS 是一个基于 Node.js 的 服务端框架，使用 TypeScript 编写，架构风格借鉴了 Angular。特点包括：

\n\n

适合做什么？​

\n\n

前置知识​

\n\n
\n

二、环境准备与创建项目​

\n

环境要求​

\n\n

使用 CLI 创建项目​

\n

安装 Nest CLI（可选，也可用 npx 不全局安装）：

\n
npm i -g @nestjs/cli
nest new my-app
\n

或直接用 npx：

\n
npx @nestjs/cli new my-app
\n

按提示选择包管理器（npm / yarn / pnpm），完成后进入项目并启动：

\n
cd my-app
npm run start
\n

浏览器访问 http://localhost:3000 应看到 Hello World!。

\n

常用脚本​

\n
命令说明
npm run start开发模式（默认端口 3000）
npm run start:dev监听文件变化自动重启
npm run start:debug调试模式
npm run build编译为 JavaScript 到 dist/
npm run start:prod以生产模式运行 dist/
\n
开发时建议

日常开发用 npm run start:dev，保存即热重载。

\n
\n

三、项目目录结构​

\n
my-app/
├── src/
│   ├── app.module.ts      # 根模块
│   ├── app.controller.ts  # 根控制器
│   ├── app.service.ts     # 根服务
│   └── main.ts            # 入口文件，引导 Nest 应用
├── test/                  # 测试
├── nest-cli.json          # Nest CLI 配置
├── tsconfig.json
└── package.json
\n\n

后续会按功能拆成多个模块（如 users、posts），每个模块可有自己的 *.module.ts、*.controller.ts、*.service.ts。

\n
\n

四、核心概念：模块、控制器、服务​

\n

4.1 模块（Module）​

\n

模块是组织代码的单元，把控制器、服务、其他模块组织在一起。

\n
// app.module.ts
import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';

@Module({
  imports: [],      // 其他模块
  controllers: [AppController],
  providers: [AppService],
  exports: [AppService],  // 导出后，其他模块可注入 AppService
})
export class AppModule {}
\n\n

4.2 控制器（Controller）​

\n

控制器负责处理入站请求并返回响应，对应路由与 HTTP 方法。

\n
// app.controller.ts
import { Controller, Get, Post, Body, Param } from '@nestjs/common';
import { AppService } from './app.service';

@Controller()  // 路由前缀为空，即根
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get()
  getHello(): string {
    return this.appService.getHello();
  }

  @Get('info')
  getInfo() {
    return { name: 'My App', version: '1.0' };
  }
}
\n\n

4.3 服务（Provider / Service）​

\n

服务承载业务逻辑，被控制器注入并调用，避免在控制器里写复杂逻辑。

\n
// app.service.ts
import { Injectable } from '@nestjs/common';

@Injectable()
export class AppService {
  getHello(): string {
    return 'Hello World!';
  }
}
\n\n

关系小结：请求 → 控制器（路由）→ 调用服务（业务）→ 返回响应。

\n
\n

五、依赖注入（DI）​

\n

Nest 内置 IoC 容器：你只声明「需要什么类」，容器负责创建实例并注入。

\n
@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}
  //     ↑ 私有只读    ↑ 类型声明即可，Nest 自动注入实例
}
\n\n
\n

六、路由与请求处理​

\n

6.1 路径与参数​

\n
@Controller('users')
export class UsersController {
  @Get()                      // GET /users
  findAll() { return []; }

  @Get(':id')                 // GET /users/123
  findOne(@Param('id') id: string) {
    return { id };
  }

  @Post()
  create(@Body() body: CreateUserDto) {
    return body;
  }

  @Put(':id')
  update(@Param('id') id: string, @Body() body: UpdateUserDto) {
    return { id, ...body };
  }

  @Delete(':id')
  remove(@Param('id') id: string) {
    return { deleted: id };
  }
}
\n

常用参数装饰器：

\n
装饰器含义
@Param('id')路径参数
@Query('key')查询参数
@Body()请求体（JSON）
@Headers('name')请求头
@Req() / @Res()原生 request / response（慎用，会失去部分 Nest 能力）
\n

6.2 全局路由前缀​

\n

在 main.ts 中可为所有路由加前缀：

\n
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.setGlobalPrefix('api');  // 所有路由变为 /api/...
  await app.listen(3000);
}
\n
\n

七、DTO 与验证（Validation）​

\n

7.1 为什么用 DTO​

\n\n

7.2 安装与启用​

\n
npm i class-validator class-transformer
\n

在 main.ts 中启用全局验证管道：

\n
import { ValidationPipe } from '@nestjs/common';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalPipes(new ValidationPipe({
    whitelist: true,   // 自动去掉 DTO 中未声明的属性
    forbidNonWhitelisted: true,  // 若带未声明属性则直接 400
    transform: true,   // 按类型自动转换（如 string → number）
  }));
  await app.listen(3000);
}
\n

7.3 定义 DTO​

\n
// create-user.dto.ts
import { IsString, IsEmail, MinLength, IsOptional } from 'class-validator';

export class CreateUserDto {
  @IsString()
  @MinLength(2)
  name: string;

  @IsEmail()
  email: string;

  @IsString()
  @MinLength(6)
  password: string;

  @IsOptional()
  @IsString()
  avatar?: string;
}
\n

控制器中直接使用即可，校验失败时 Nest 自动返回 400 与错误信息：

\n
@Post()
create(@Body() dto: CreateUserDto) {
  return this.usersService.create(dto);
}
\n
\n

八、管道（Pipe）​

\n

管道用于转换或校验输入数据，在到达控制器方法之前执行。

\n

8.1 内置管道示例​

\n\n
@Get(':id')
findOne(@Param('id', ParseIntPipe) id: number) {
  return this.usersService.findOne(id);
}
\n

8.2 自定义管道​

\n

实现 PipeTransform 接口即可：

\n
// parse-bool.pipe.ts
import { PipeTransform, Injectable, BadRequestException } from '@nestjs/common';

@Injectable()
export class ParseBoolPipe implements PipeTransform<string, boolean> {
  transform(value: string): boolean {
    if (value === 'true') return true;
    if (value === 'false') return false;
    throw new BadRequestException('Expected \"true\" or \"false\"');
  }
}
\n

在参数或控制器上使用：@Query('active', ParseBoolPipe) active: boolean。

\n
\n

九、守卫（Guard）​

\n

守卫决定是否允许请求继续，常用于权限、角色校验。

\n

9.1 使用方式​

\n\n

9.2 简单示例​

\n
// roles.guard.ts
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const requiredRoles = this.reflector.get<string[]>('roles', context.getHandler());
    if (!requiredRoles) return true;
    const { user } = context.switchToHttp().getRequest();
    return requiredRoles.some((role) => user?.roles?.includes(role));
  }
}
\n

通过 Reflector 读取元数据（如自定义装饰器 @Roles('admin')），再根据 user 判断。若返回 false，Nest 默认返回 403。

\n
\n

十、拦截器（Interceptor）​

\n

拦截器可在请求前/后统一处理逻辑，如日志、超时、响应格式封装等。

\n

10.1 响应映射示例​

\n
// transform.interceptor.ts
import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';

export interface Response<T> {
  data: T;
  timestamp: string;
}

@Injectable()
export class TransformInterceptor<T> implements NestInterceptor<T, Response<T>> {
  intercept(context: ExecutionContext, next: CallHandler): Observable<Response<T>> {
    return next.handle().pipe(
      map((data) => ({
        data,
        timestamp: new Date().toISOString(),
      })),
    );
  }
}
\n

在 main.ts 中全局注册：app.useGlobalInterceptors(new TransformInterceptor());，则所有控制器返回的数据会被包成 { data, timestamp }。

\n

10.2 典型用途​

\n\n
\n

十一、异常与异常过滤器​

\n

11.1 内置 HTTP 异常​

\n

在服务或控制器中直接抛出，Nest 会转为对应状态码的 JSON：

\n
import { NotFoundException, BadRequestException } from '@nestjs/common';

throw new NotFoundException('用户不存在');
throw new BadRequestException('参数错误');
\n

常用：BadRequestException(400)、UnauthorizedException(401)、ForbiddenException(403)、NotFoundException(404) 等。

\n

11.2 异常过滤器（Exception Filter）​

\n

若希望统一格式或对特定异常做特殊处理，可写异常过滤器：

\n
@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const status = exception.getStatus();
    const result = exception.getResponse();
    response.status(status).json({
      statusCode: status,
      message: typeof result === 'object' ? (result as any).message : result,
      timestamp: new Date().toISOString(),
    });
  }
}
\n

使用：@UseFilters(HttpExceptionFilter) 或 app.useGlobalFilters(new HttpExceptionFilter())。

\n
\n

十二、中间件（Middleware）​

\n

中间件在路由处理器之前执行，可做日志、解析、限流等。

\n

12.1 定义与注册​

\n
// logger.middleware.ts
import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';

@Injectable()
export class LoggerMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    console.log(`${req.method} ${req.url}`);
    next();
  }
}
\n

在模块中挂到指定路由：

\n
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(LoggerMiddleware).forRoutes('*');
  }
}
\n

12.2 函数式中间件​

\n

若无需依赖注入，可写为普通函数，在 consumer.apply(LoggerMiddleware) 处传入即可。

\n
\n

十三、配置（ConfigModule）​

\n

13.1 使用 @nestjs/config​

\n
npm i @nestjs/config
\n

根模块中引入：

\n
import { ConfigModule } from '@nestjs/config';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: ['.env.local', '.env'],
    }),
  ],
})
export class AppModule {}
\n

13.2 读取配置​

\n

在服务或控制器中注入 ConfigService：

\n
constructor(private config: ConfigService) {}

someMethod() {
  const port = this.config.get<number>('PORT', 3000);
  const dbUrl = this.config.get<string>('DATABASE_URL');
}
\n

推荐配合 .env 文件，不要提交敏感信息。

\n
\n

十四、数据库（TypeORM 简介）​

\n

Nest 与 TypeORM、Prisma 等都能很好集成，这里以 TypeORM 为例说明「模块 + 实体」的用法。

\n

14.1 安装​

\n
npm i @nestjs/typeorm typeorm mysql2
\n

14.2 注册与实体​

\n
// app.module.ts
import { TypeOrmModule } from '@nestjs/typeorm';
import { User } from './users/user.entity';

@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: 'mysql',
      host: 'localhost',
      port: 3306,
      username: 'root',
      password: 'xxx',
      database: 'mydb',
      entities: [User],
      synchronize: true,  // 开发时可 true，生产建议 false + 迁移
    }),
    TypeOrmModule.forFeature([User]),  // 在 UsersModule 中
  ],
})
export class AppModule {}
\n

14.3 实体与在服务中注入 Repository​

\n
// user.entity.ts
import { Entity, Column, PrimaryGeneratedColumn } from 'typeorm';

@Entity('users')
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  name: string;

  @Column({ unique: true })
  email: string;
}
\n
// users.service.ts
@Injectable()
export class UsersService {
  constructor(
    @InjectRepository(User)
    private userRepo: Repository<User>,
  ) {}

  async findAll(): Promise<User[]> {
    return this.userRepo.find();
  }
}
\n

更多（关系、迁移、事务）请查阅 TypeORM 文档。

\n
\n

十五、认证（JWT 示例）​

\n

认证涉及「登录签发 token」和「请求时校验 token」，常用 Passport + JWT。

\n

15.1 安装​

\n
npm i @nestjs/passport @nestjs/jwt passport passport-jwt passport-local
npm i -D @types/passport-jwt @types/passport-local
\n

15.2 思路简述​

\n\n

15.3 配置与使用​

\n

在模块中注册：

\n
JwtModule.register({
  secret: process.env.JWT_SECRET || 'your-secret',
  signOptions: { expiresIn: '7d' },
}),
PassportModule,
\n

在需要登录的控制器或方法上添加：

\n
@UseGuards(JwtAuthGuard)
@Get('profile')
getProfile(@Request() req) {
  return req.user;
}
\n

具体实现可参考官方文档 NestJS 认证。

\n
\n

十六、测试​

\n

16.1 单元测试（服务）​

\n

使用 Jest，对服务类进行隔离测试，依赖用 mock：

\n
describe('AppService', () => {
  let service: AppService;

  beforeEach(async () => {
    const module = await Test.createTestingModule({
      providers: [AppService],
    }).compile();
    service = module.get<AppService>(AppService);
  });

  it('getHello', () => {
    expect(service.getHello()).toBe('Hello World!');
  });
});
\n

16.2 E2E 测试​

\n

对完整 HTTP 请求做测试：

\n
describe('AppController (e2e)', () => {
  it('/ (GET)', () => {
    return request(app.getHttpServer())
      .get('/')
      .expect(200)
      .expect('Hello World!');
  });
});
\n

运行：npm run test（单元）、npm run test:e2e（E2E）。

\n
\n

十七、构建与部署​

\n

17.1 构建​

\n
npm run build
\n

产物在 dist/，为编译后的 JavaScript。

\n

17.2 生产运行​

\n
npm run start:prod
\n

会执行 node dist/main（或你配置的入口）。生产环境建议用 PM2、Docker 或云平台的 Node 运行时，并设置好环境变量（如 NODE_ENV=production、数据库与 JWT 的配置）。

\n

17.3 部署注意点​

\n\n
\n

十八、学习路径小结​

\n
    \n
  1. 入门：创建项目 → 理解 Module / Controller / Service → 改根路由看效果
    2. \n
  2. 请求：路由、@Param / @Query / @Body、DTO + ValidationPipe
    3. \n
  3. 结构：按功能拆模块（如 UsersModule）、依赖注入与 exports
    4. \n
  4. 增强：管道、守卫、拦截器、异常过滤器、中间件
    5. \n
  5. 数据：ConfigModule、TypeORM/Prisma、实体与 Repository
    6. \n
  6. 安全：JWT 认证、角色守卫
    7. \n
  7. 质量：单元测试、E2E 测试
    8. \n
  8. 上线：build、环境变量、进程管理、健康检查
    9. \n
\n

遇到问题可查阅 NestJS 官方文档。

", "url": "https://老王.me/blog/nestjs-tutorial", "title": "NestJS 完整教程（新手向）", "summary": "由浅入深学习 NestJS，覆盖控制器、服务、模块、依赖注入、管道、守卫、拦截器、数据库、认证与部署等主要知识点。", "date_modified": "2026-03-19T09:16:45.000Z", "tags": [] }, { "id": "https://老王.me/blog/nodejs-tutorial", "content_html": "

本教程面向零基础或刚接触 Node.js 的开发者，按由浅入深的顺序讲解所有主要知识点。建议按章节顺序阅读。

\n
\n

一、Node.js 简介​

\n

Node.js 是什么？​

\n

Node.js 是一个让 JavaScript 在服务器端运行的运行时环境。它解决了浏览器只能运行 JS 的限制，让你可以用 JS 写：

\n\n

Node 与浏览器的主要区别​

\n\n
\n

二、环境准备与 npm​

\n

安装 Node.js​

\n\n

确认版本：

\n
node -v
npm -v
\n

初始化项目​

\n
mkdir my-node-app
cd my-node-app
npm init -y
\n

package.json 基本字段​

\n\n

例如加入开发脚本：

\n
{
  \"scripts\": {
    \"dev\": \"node src/server.js\"
  }
}
\n
\n

三、模块系统（CommonJS / ESM）​

\n

CommonJS：require​

\n
// src/math.cjs
function add(a, b) {
  return a + b
}

module.exports = { add }
\n
// src/main.cjs
const { add } = require('./math.cjs')
console.log(add(1, 2))
\n

ESM：import​

\n
// src/math.mjs
export function add(a, b) {
  return a + b
}
\n
// src/main.mjs
import { add } from './math.mjs'
console.log(add(1, 2))
\n

建议你在新项目中统一一种模块方式（ESM 更现代），并结合团队约定。

\n
\n

四、异步与事件循环​

\n

Promise / async-await​

\n
async function main() {
  const res = await Promise.resolve({ ok: true })
  console.log(res.ok)
}

main()
\n

错误处理​

\n
async function run() {
  try {
    throw new Error('boom')
  } catch (e) {
    console.error('捕获错误：', e.message)
  }
}
\n
\n

五、HTTP 服务示例（原生）​

\n

创建 src/server.js：

\n
const http = require('http')

const server = http.createServer((req, res) => {
  if (req.url === '/health') {
    res.setHeader('Content-Type', 'application/json; charset=utf-8')
    res.end(JSON.stringify({ ok: true }))
    return
  }

  res.statusCode = 404
  res.end('Not Found')
})

server.listen(3000, () => {
  console.log('server running at http://localhost:3000')
})
\n

启动：

\n
node src/server.js
\n

访问：http://localhost:3000/health

\n
\n

六、使用 Express 构建 API​

\n

安装​

\n
npm i express
\n

简单路由​

\n

创建 src/app.js：

\n
const express = require('express')

const app = express()
app.use(express.json())

app.get('/health', (_req, res) => {
  res.json({ ok: true })
})

app.post('/echo', (req, res) => {
  res.json({ received: req.body })
})

app.listen(3000, () => {
  console.log('express running at http://localhost:3000')
})
\n

启动：

\n
node src/app.js
\n
\n

七、数据访问（入门思路）​

\n

新手建议先把“接口层”和“数据层”分开。你可以从简单存储开始，例如：

\n\n

等接口逻辑稳定后再替换为数据库（如 PostgreSQL / MySQL）。

\n
\n

八、日志与错误处理​

\n

统一错误返回​

\n

Express 可以通过中间件做统一处理：

\n
app.use((err, _req, res, _next) => {
  console.error(err)
  res.status(500).json({ message: 'internal error' })
})
\n

日志建议​

\n\n
\n

九、测试与调试​

\n

Jest 示例（单元测试）​

\n
npm i -D jest
\n

在 package.json 添加：

\n
{
  \"scripts\": {
    \"test\": \"jest\"
  }
}
\n

写测试：

\n
function add(a, b) {
  return a + b
}

test('add', () => {
  expect(add(1, 2)).toBe(3)
})
\n

调试​

\n\n
\n

十、部署与小结​

\n

部署常见方式​

\n\n

小结​

\n\n
\n

十一、学习路径小结​

\n
    \n
  1. 安装 Node 并完成 npm 项目初始化
    2. \n
  2. 理解模块系统（require/import）
    3. \n
  3. 写几个 async/await 的函数并练习错误捕获
    4. \n
  4. 用原生 http 实现 /health
    5. \n
  5. 用 Express 做一个最小 API（health + echo）
    6. \n
  6. 加上至少 1-2 个 Jest 单测，再考虑部署
    7. \n
\n

遇到问题可查阅 Node.js 官方文档 与社区示例。

", "url": "https://老王.me/blog/nodejs-tutorial", "title": "Node.js 完整教程（新手向）", "summary": "由浅入深学习 Node.js，覆盖环境与 npm、模块系统、异步与事件循环、HTTP 与 Express、日志错误处理、测试与部署等主要知识点。", "date_modified": "2026-03-19T15:11:56.000Z", "tags": [] }, { "id": "https://老王.me/blog/python-tutorial", "content_html": "

本教程面向零基础或刚接触 Python 的开发者，按由浅入深的顺序讲解所有主要知识点。建议按章节顺序阅读。

\n
\n

一、Python 简介​

\n

什么是 Python？​

\n

Python 是一种 解释型、面向对象且以 可读性强 著称的编程语言。它的生态非常成熟，常见用途包括：

\n\n

适合做什么？​

\n\n
\n

二、环境准备与运行方式​

\n

安装 Python​

\n\n

创建虚拟环境（强烈建议）​

\n

避免把依赖装到全局 Python，造成版本冲突：

\n
python -m venv .venv
\n

激活虚拟环境：

\n
# macOS / Linux
source .venv/bin/activate

# Windows（PowerShell）
.\\.venv\\Scripts\\Activate.ps1
\n

升级 pip 并安装依赖：

\n
python -m pip install -U pip
\n
\n

提示：创建虚拟环境可以让每个项目的依赖互相独立，更容易复现和部署。

\n
\n

运行脚本​

\n
python main.py
\n

也可以直接用模块方式运行：

\n
python -m pip --version
\n
\n

三、基本语法与数据类型​

\n

变量与常量​

\n

Python 不需要写类型声明：

\n
name = \"Alice\"
age = 18
is_student = True
\n

常用数据类型​

\n\n

字符串拼接：f-string​

\n
user = \"Bob\"
score = 95.5
print(f\"{user} 的得分是 {score}\")
\n
\n

四、条件与循环​

\n

条件分支​

\n
age = 20
if age >= 18:
    print(\"adult\")
else:
    print(\"teen\")
\n

循环​

\n
for i in range(5):
    print(i)

items = [\"a\", \"b\", \"c\"]
for item in items:
    print(item)
\n

while 循环：

\n
count = 0
while count < 3:
    count += 1
    print(count)
\n
\n

五、函数与模块​

\n

函数定义与返回值​

\n
def add(a: int, b: int) -> int:
    return a + b
\n

其中：

\n\n

模块与导入​

\n

假设有 utils.py：

\n
# utils.py
def hello(name: str) -> str:
    return f\"hello, {name}\"
\n

在 main.py：

\n
from utils import hello

print(hello(\"world\"))
\n
\n

六、面向对象与异常处理​

\n

类与对象​

\n
class User:
    def __init__(self, name: str):
        self.name = name

    def greet(self) -> str:
        return f\"hi, {self.name}\"

u = User(\"Tom\")
print(u.greet())
\n

异常（try / except）​

\n
try:
    n = int(\"123\")
except ValueError as e:
    print(\"转换失败：\", e)
\n

也可以在捕获后重新抛出：

\n
try:
    n = int(\"abc\")
except ValueError as e:
    raise RuntimeError(\"输入不是数字\") from e
\n
\n

七、文件与数据格式​

\n

读写文件​

\n
with open(\"data.txt\", \"w\", encoding=\"utf-8\") as f:
    f.write(\"Hello\\n\")

with open(\"data.txt\", \"r\", encoding=\"utf-8\") as f:
    content = f.read()
print(content)
\n

JSON​

\n
import json

obj = {\"name\": \"Alice\", \"age\": 18}

with open(\"data.json\", \"w\", encoding=\"utf-8\") as f:
    json.dump(obj, f, ensure_ascii=False, indent=2)

with open(\"data.json\", \"r\", encoding=\"utf-8\") as f:
    data = json.load(f)
print(data[\"name\"])
\n
\n

八、类型标注与项目结构​

\n

当项目变大时，类型标注可以提升可维护性。一个常见结构：

\n
my-project/
├── src/
│   └── app/
│       ├── main.py
│       └── services/
├── tests/
├── pyproject.toml  (或 requirements.txt)
└── README.md
\n

类型检查工具常见包括 mypy（可按需启用）。

\n
\n

九、第三方库与包管理​

\n

requirements.txt​

\n

安装依赖：

\n
pip install requests
\n

生成依赖清单：

\n
pip freeze > requirements.txt
\n

在新环境安装：

\n
pip install -r requirements.txt
\n

常用库举例​

\n\n
\n

十、Web 入门（FastAPI）​

\n

安装​

\n
pip install fastapi uvicorn
\n

最小服务​

\n

创建 main.py：

\n
from fastapi import FastAPI

app = FastAPI()

@app.get(\"/health\")
def health():
    return {\"ok\": True}
\n

启动服务：

\n
uvicorn main:app --reload --port 8000
\n

访问：http://localhost:8000/health

\n
\n

十一、测试与调试​

\n

安装 pytest​

\n
pip install -U pytest
\n

写测试示例：tests/test_main.py

\n
def test_add():
    assert 1 + 1 == 2
\n

运行：

\n
pytest
\n

调试小技巧​

\n\n
\n

十二、部署与小结​

\n

部署思路​

\n\n

小结​

\n\n
\n

十三、学习路径小结​

\n
    \n
  1. 学会变量、函数、循环与常见数据结构
    2. \n
  2. 逐步引入类型标注，让代码更易维护
    3. \n
  3. 熟悉虚拟环境与依赖管理（requirements）
    4. \n
  4. 做一个简单 Web 服务（FastAPI）
    5. \n
  5. 写至少几条测试（pytest），再逐步扩展项目
    6. \n
\n

遇到问题可查阅 Python 官方文档 与社区示例。

", "url": "https://老王.me/blog/python-tutorial", "title": "Python 完整教程（新手向）", "summary": "由浅入深学习 Python，覆盖语法基础、类型标注、异常处理、第三方库、Web 入门、测试、调试与部署等主要知识点。", "date_modified": "2026-03-19T15:11:56.000Z", "tags": [] }, { "id": "https://老王.me/blog/go-tutorial", "content_html": "

本教程面向零基础或刚接触 Go 的开发者，按由浅入深的顺序讲解所有主要知识点。建议按章节顺序阅读。

\n
\n

一、Go 简介​

\n

Go 是什么？​

\n

Go（又称 Golang）是一种由 Google 主导开发的编程语言，特点包括：

\n\n

适合做什么？​

\n\n
\n

二、安装与工作区​

\n

安装 Go​

\n\n
go version
\n

创建模块（Go Modules）​

\n
mkdir my-go-app
cd my-go-app
go mod init example.com/my-go-app
\n

Go 的依赖管理通常基于 go.mod。

\n
\n

三、基础语法​

\n

最小可运行程序​

\n

创建 main.go：

\n
package main

import \"fmt\"

func main() {
\tfmt.Println(\"Hello, Go!\")
}
\n

变量与常量​

\n
var name = \"Alice\"
var age int = 18
const appName = \"my-app\"
\n

常用类型​

\n\n
\n

四、函数、包与模块​

\n

函数​

\n
func add(a int, b int) int {
\treturn a + b
}
\n

包​

\n

Go 用目录划分包，例如：

\n
my-go-app/
├── main.go
└── utils/
    └── math.go
\n

utils/math.go：

\n
package utils

func Add(a int, b int) int {
\treturn a + b
}
\n

在 main.go 中使用：

\n
import \"example.com/my-go-app/utils\"
\n
\n

五、结构体与接口​

\n

结构体（struct）​

\n
type User struct {
\tName string
\tAge  int
}
\n

方法​

\n
func (u User) Greet() string {
\treturn fmt.Sprintf(\"hi, %s\", u.Name)
}
\n

接口（interface）​

\n

接口关注“行为”，而不是具体类型：

\n
type Greeter interface {
\tGreet() string
}

func SayHello(g Greeter) {
\tfmt.Println(g.Greet())
}
\n
\n

六、并发：goroutine 与 channel​

\n

goroutine​

\n
go func() {
\tfmt.Println(\"running in goroutine\")
}()
\n

channel 通信​

\n
ch := make(chan int)

go func() {
\tch <- 42
}()

v := <-ch
fmt.Println(v)
\n
\n

七、错误处理​

\n

Go 的错误处理通常是显式返回 error：

\n
import \"errors\"

func findUser(id int) (string, error) {
\tif id <= 0 {
\t\treturn \"\", errors.New(\"invalid id\")
\t}
\treturn \"Alice\", nil
}
\n

调用方：

\n
name, err := findUser(1)
if err != nil {
\tfmt.Println(\"error:\", err)
\treturn
}
fmt.Println(name)
\n
\n

八、HTTP 服务示例​

\n

创建 server/main.go：

\n
package main

import (
\t\"encoding/json\"
\t\"net/http\"
)

func main() {
\thttp.HandleFunc(\"/health\", func(w http.ResponseWriter, _ *http.Request) {
\t\tw.Header().Set(\"Content-Type\", \"application/json; charset=utf-8\")
\t\t_ = json.NewEncoder(w).Encode(map[string]any{\"ok\": true})
\t})

\thttp.ListenAndServe(\":3000\", nil)
}
\n

运行：

\n
go run ./server
\n

访问：http://localhost:3000/health

\n
\n

九、测试与工具​

\n

基础测试​

\n

在 utils/math_test.go：

\n
package utils

import \"testing\"

func TestAdd(t *testing.T) {
\tgot := Add(1, 2)
\tif got != 3 {
\t\tt.Fatalf(\"expected 3, got %d\", got)
\t}
}
\n

运行测试：

\n
go test ./...
\n
\n

十、部署与小结​

\n

构建​

\n
go build -o app .
\n

交叉编译（示例）​

\n
GOOS=linux GOARCH=amd64 go build -o app .
\n

小结​

\n\n
\n

十一、学习路径小结​

\n
    \n
  1. 跑通 go mod init 并完成一个 main.go
    2. \n
  2. 学会结构体与方法、接口与多态
    3. \n
  3. 写至少一个 goroutine + channel 的例子
    4. \n
  4. 做一个 /health 的 HTTP 服务
    5. \n
  5. 补上测试：至少 1-2 个 go test 用例
    6. \n
\n

遇到问题可查阅 Go 官方文档。

", "url": "https://老王.me/blog/go-tutorial", "title": "Go 完整教程（新手向）", "summary": "由浅入深学习 Go，覆盖基础语法、包与模块、结构体与接口、错误处理、并发（goroutine/channel）、HTTP 服务、测试与部署等主要知识点。", "date_modified": "2026-03-19T15:11:56.000Z", "tags": [] }, { "id": "https://老王.me/blog/php-tutorial", "content_html": "

本教程面向零基础或刚接触 PHP 的开发者，按由浅入深的顺序讲解所有主要知识点。建议按章节顺序阅读。

\n
\n

一、PHP 简介​

\n

PHP 是什么？​

\n

PHP 是一种非常成熟的服务端脚本语言，主要用于构建 Web 应用与后端接口。它的生态非常丰富，常见用途包括：

\n\n

适合做什么？​

\n\n
\n

二、安装与开发方式​

\n

安装 PHP​

\n\n
php -v
\n

本地快速启动（内置服务器）​

\n

假设你有一个 public/ 目录：

\n
php -S localhost:8000 -t public
\n

然后访问：http://localhost:8000

\n
\n

三、基础语法​

\n

变量与输出​

\n
<?php
$name = \"Alice\";
$age = 18;

echo \"Hello, {$name}\\n\";
echo \"Age: {$age}\\n\";
\n

条件与循环​

\n
<?php
$score = 90;

if ($score >= 90) {
  echo \"A\\n\";
} else {
  echo \"B\\n\";
}

for ($i = 0; $i < 3; $i++) {
  echo $i . \"\\n\";
}
\n
\n

四、函数与作用域​

\n

定义函数​

\n
<?php
function add(int $a, int $b): int {
  return $a + $b;
}

echo add(1, 2); // 3
\n

作用域与变量​

\n

注意函数内部变量的作用域规则：函数内创建的变量默认不会自动暴露到全局作用域中。

\n
\n

五、面向对象（OOP）​

\n

类与对象​

\n
<?php
class User {
  public string $name;

  public function __construct(string $name) {
    $this->name = $name;
  }

  public function greet(): string {
    return \"hi, {$this->name}\";
  }
}

$u = new User(\"Tom\");
echo $u->greet();
\n

继承（了解）​

\n
<?php
class Admin extends User {
  public function role(): string {
    return \"admin\";
  }
}
\n
\n

六、命名空间与 Composer（包管理）​

\n

安装 Composer​

\n\n

初始化项目与引入依赖​

\n
composer init
composer require guzzlehttp/guzzle
\n

然后即可在代码中使用第三方库（具体 API 以库文档为准）。

\n
\n

七、数据库（PDO 简例）​

\n

PDO 基础连接​

\n
<?php
$dsn = \"mysql:host=localhost;dbname=mydb;charset=utf8mb4\";
$user = \"root\";
$password = \"xxx\";

$pdo = new PDO($dsn, $user, $password, [
  PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);
\n

使用预处理（防 SQL 注入）​

\n
<?php
$stmt = $pdo->prepare(\"SELECT * FROM users WHERE id = :id\");
$stmt->execute([':id' => 1]);
$row = $stmt->fetch(PDO::FETCH_ASSOC);

var_dump($row);
\n
\n

八、简单 Web 服务示例（路由思路）​

\n

你可以用“单入口文件”来做最基础的路由分发（新手学习用）：

\n

public/index.php：

\n
<?php

$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);

if ($path === '/health') {
  header('Content-Type: application/json; charset=utf-8');
  echo json_encode(['ok' => true], JSON_UNESCAPED_UNICODE);
  exit;
}

http_response_code(404);
echo \"Not Found\";
\n

启动后访问：/health

\n
\n

九、测试与质量​

\n

安装 PHPUnit​

\n
composer require --dev phpunit/phpunit
\n

写一个简单测试：tests/MathTest.php

\n
<?php

use PHPUnit\\Framework\\TestCase;

final class MathTest extends TestCase {
  public function testAdd(): void {
    $this->assertSame(3, 1 + 2);
  }
}
\n

运行：

\n
vendor/bin/phpunit
\n
\n

十、部署与小结​

\n

部署思路​

\n\n

小结​

\n\n
\n

十一、学习路径小结​

\n
    \n
  1. 跑通 php -S 并写一个 /health 接口
    2. \n
  2. 掌握基础语法与函数（至少 3-5 个练习题）
    3. \n
  3. 学会 OOP 并写一个 User 类
    4. \n
  4. 使用 Composer 引入一个库，并写一次调用
    5. \n
  5. 用 PDO 写一个带预处理的查询示例
    6. \n
  6. 最少写 1 个 PHPUnit 测试并运行通过
    7. \n
\n

遇到问题可查阅 PHP 官方文档。

", "url": "https://老王.me/blog/php-tutorial", "title": "PHP 完整教程（新手向）", "summary": "由浅入深学习 PHP，覆盖基础语法、面向对象、Composer 与包管理、PDO 数据访问、简单 Web 服务、测试与部署等主要知识点。", "date_modified": "2026-03-19T15:11:56.000Z", "tags": [] }, { "id": "https://老王.me/blog/docusaurus-tutorial", "content_html": "

本教程面向零基础或刚接触 Docusaurus 的开发者，按由浅入深的顺序讲解所有主要知识点。建议按章节顺序阅读。

\n
\n

一、Docusaurus 简介​

\n

什么是 Docusaurus？​

\n

Docusaurus 是 Meta（Facebook）开源 的静态站点生成器，专门为 文档站、博客、产品主页 设计。特点包括：

\n\n

适合做什么？​

\n\n
\n

二、环境准备与创建项目​

\n

环境要求​

\n\n

创建新项目​

\n

使用官方脚手架（经典模板）：

\n
npm init docusaurus@latest my-website classic
\n

按提示选择：

\n\n

进入项目并启动开发服务器：

\n
cd my-website
npm run start
\n

在浏览器打开 http://localhost:3000 即可看到默认站点。

\n
WSL / 远程开发

若在 WSL 中运行、用 Windows 浏览器访问，需让开发服务器监听所有网卡。在 package.json 中把启动脚本改为：

\"start\": \"docusaurus start --host 0.0.0.0\"

然后可用 WSL 的 IP 访问，如 http://172.x.x.x:3000。

\n
\n

三、项目目录结构​

\n

理解目录结构有助于后续自定义和排查问题。

\n
my-website/
├── blog/                 # 博客文章（按日期或文件夹组织）
├── docs/                 # 文档源文件（Markdown/MDX）
├── src/
│   ├── components/       # 自定义 React 组件
│   ├── css/              # 全局样式（如 custom.css）
│   └── pages/            # 独立页面，对应站点路由
├── static/               # 静态资源（图片、favicon 等），会原样复制到站点根目录
├── docusaurus.config.ts  # 站点主配置
├── sidebars.ts           # 文档侧边栏配置
└── package.json
\n

重点目录说明：

\n
目录/文件作用
docs/所有「文档」类页面，自动参与侧边栏与导航
blog/博客文章，自动按时间列表与归档
src/pages/自定义页面，每个文件对应一个路由（如 about.js → /about）
static/放图片、PDF 等，引用时路径从根写起，如 /img/logo.png
docusaurus.config.ts站点标题、URL、主题、插件、导航栏、页脚等
sidebars.ts文档侧边栏顺序与分组
\n
\n

四、编写文档（docs）​

\n

4.1 新建一篇文档​

\n

在 docs/ 下新建任意 .md 或 .mdx 文件即可，例如：

\n
# 例如
docs/quick-start.md
docs/guide/install.md
\n

文件顶部可写 Front Matter（YAML），用于配置当前页在侧边栏和 SEO 等行为。

\n

4.2 Front Matter 常用字段​

\n
---
# 侧边栏显示的文字（默认用标题）
sidebar_label: 快速开始
# 侧边栏中的排序，数字越小越靠前
sidebar_position: 1
# 页面标题（浏览器标签、SEO）
title: 快速开始
# 页面描述（SEO）
description: 5 分钟上手 Docusaurus
# 自定义 URL 最后一段，默认用文件名
slug: /quick-start
# 是否在侧边栏中隐藏
sidebar_class_name: 可选 CSS 类名
---
\n

示例：

\n
docs/quick-start.mdmd
---
sidebar_label: 快速开始
sidebar_position: 1
title: 快速开始
---

# 快速开始

这里是正文……
\n

保存后，开发服务器会热更新，文档会出现在侧边栏并可按 sidebar_position 排序。

\n

4.3 文档之间的链接​

\n\n
[安装说明](./install)
[介绍](/docs/intro)
\n\n
[介绍](intro.md)
\n
\n

五、侧边栏（Sidebar）配置​

\n

5.1 自动生成（默认）​

\n

在 sidebars.ts 中常见写法：

\n
const sidebars: SidebarsConfig = {
  tutorialSidebar: [{ type: 'autogenerated', dirName: '.' }],
};
\n

表示根据 docs/ 的目录和文件名自动生成侧边栏，顺序由各文档的 sidebar_position 和文件名共同决定。

\n

5.2 用文件夹分组（分类）​

\n

在 docs/ 下建子文件夹，并在该文件夹内放一个 _category_.json 即可成为一个「分类」：

\n
// docs/guide/_category_.json
{
  \"label\": \"使用指南\",
  \"position\": 2,
  \"link\": {
    \"type\": \"generated-index\",
    \"title\": \"指南索引\",
    \"description\": \"按主题查阅使用说明。\"
  }
}
\n\n

5.3 手动配置侧边栏​

\n

若需要完全自定义顺序和结构，可在 sidebars.ts 中手写：

\n
const sidebars: SidebarsConfig = {
  tutorialSidebar: [
    'intro',
    'quick-start',
    {
      type: 'category',
      label: '使用指南',
      items: ['guide/install', 'guide/usage'],
    },
  ],
};
\n\n
\n

六、Markdown 与 MDX​

\n

6.1 支持的 Markdown 语法​

\n

Docusaurus 使用 MDX（Markdown + JSX），所以普通 Markdown 都支持，例如：

\n\n

代码块可指定语言和标题：

\n
```js title=\"utils.js\"
export function add(a, b) {
  return a + b;
}
```
\n

6.2 使用 Admonition（提示框）​

\n

内置的「提示框」组件，适合做说明、注意、警告等：

\n
:::note[说明]
这是一段说明文字。
:::

:::tip[提示]
小技巧。
:::

:::danger[注意]
谨慎操作。
:::

:::info[信息]
补充信息。
:::

:::caution[警告]
可能带来的风险。
:::
\n

6.3 在 MDX 中使用 React 组件​

\n

文件扩展名改为 .mdx 后，可直接写 JSX：

\n
import MyComponent from '@site/src/components/MyComponent';

## 章节标题

普通 Markdown 内容……

<MyComponent name=\"Docusaurus\" />
\n

可引入 src/components/ 下的自定义组件，或 Docusaurus 内置组件（如 TOCInline、CodeBlock 等）。

\n

6.4 在 Markdown 中插入 JSX（不换 .mdx）​

\n

若保持 .md 扩展名，仍可使用部分「类似 HTML」的写法，但复杂组件建议用 .mdx 并 import。

\n
\n

七、博客（Blog）​

\n

7.1 文章放在哪​

\n\n

文件名中的日期会用于排序和 URL。

\n

7.2 博客 Front Matter​

\n
---
slug: my-first-post
title: 我的第一篇文章
authors: [slorber]
tags: [hello, docusaurus]
date: 2024-03-15
---

正文……
\n\n

7.3 关闭或自定义博客​

\n

在 docusaurus.config.ts 的 preset 中可关闭博客或改路径：

\n
presets: [
  [
    'classic',
    {
      blog: {
        path: 'news',        // 博客路径改为 /news
        showReadingTime: true,
        blogTitle: '动态',
      },
    },
  ],
],
\n
\n

八、自定义页面（src/pages）​

\n

8.1 约定式路由​

\n

src/pages/ 下的文件会变成站点路由：

\n\n

8.2 页面写法​

\n

可以是 React 函数组件，导出默认组件即可：

\n
// src/pages/about.js
import React from 'react';
import Layout from '@theme/Layout';

export default function About() {
  return (
    <Layout title=\"关于\" description=\"关于本站\">
      <main>
        <h1>关于我们</h1>
        <p>这里是关于页内容。</p>
      </main>
    </Layout>
  );
}
\n

使用 <Layout> 可保持与全站一致的导航栏、侧边栏和页脚。

\n

8.3 覆盖首页​

\n

若想完全自定义首页，可修改或替换 src/pages/index.js，或通过 docusaurus.config.ts 的 plugins 配置首页路由。

\n
\n

九、导航栏与页脚​

\n

9.1 导航栏（navbar）​

\n

在 docusaurus.config.ts 的 themeConfig.navbar 中配置：

\n
themeConfig: {
  navbar: {
    title: '我的站点',
    logo: {
      alt: 'Logo',
      src: 'img/logo.svg',
    },
    items: [
      { type: 'docSidebar', sidebarId: 'tutorialSidebar', label: '文档', position: 'left' },
      { to: '/blog', label: '博客', position: 'left' },
      { type: 'docsVersionDropdown', position: 'right' },
      { type: 'localeDropdown', position: 'right' },
      { href: 'https://github.com/xxx', label: 'GitHub', position: 'right' },
    ],
  },
},
\n\n

9.2 页脚（footer）​

\n

在 themeConfig.footer 中配置链接和版权信息，结构与 navbar 类似，可设多列链接和 copyright 文案。

\n
\n

十、主题与样式​

\n

10.1 全局样式​

\n

在 src/css/custom.css 中写全局 CSS，会作用于全站。例如修改主题色、字体等：

\n
:root {
  --ifm-color-primary: #2e8555;
  --ifm-font-family-base: 'Your Font', system-ui, sans-serif;
}
\n

10.2 深色模式​

\n

默认支持跟随系统或手动切换。在 themeConfig.colorMode 中可配置：

\n
colorMode: {
  defaultMode: 'light',
  respectPrefersColorScheme: true,
},
\n

10.3 自定义组件样式​

\n\n
\n

十一、配置文件（docusaurus.config）​

\n

11.1 核心字段​

\n
字段说明
title站点标题
url站点最终访问的根 URL（部署后要改）
baseUrl子路径，如 GitHub Pages 用 '/projectName/'
faviconfavicon 路径
organizationName / projectName常用于 GitHub 部署与编辑链接
presets预设（如 classic），以及 docs/blog 等开关与选项
themeConfig导航栏、页脚、颜色、Algolia 搜索等
plugins插件列表
i18n多语言配置
\n

11.2 多语言（i18n）​

\n
i18n: {
  defaultLocale: 'zh-Hans',
  locales: ['zh-Hans', 'en'],
},
\n

然后在项目根执行：

\n
npm run write-translations
\n

会在 i18n/ 下生成待翻译的 JSON，翻译后构建时会生成各语言版本。

\n

11.3 文档版本（Versioning）​

\n

适用于「多个大版本文档并存」的场景。首次为当前内容打一个版本：

\n
npm run docusaurus docs:version 1.0
\n

会生成 versioned_docs/version-1.0/ 等，并在导航栏出现版本选择器。新文档继续在 docs/ 写，代表「当前/下一版」。

\n
\n

十二、构建与部署​

\n

12.1 本地构建​

\n
npm run build
\n

产物在 build/ 目录，为静态 HTML/CSS/JS。

\n

12.2 本地预览构建结果​

\n
npm run serve
\n

会以生产模式打开 build/ 内容，用于检查部署效果。

\n

12.3 部署到 GitHub Pages​

\n\n
\"scripts\": {
  \"deploy\": \"docusaurus deploy\"
}
\n\n
url: 'https://你的用户名.github.io',
baseUrl: '/仓库名/',
projectName: '仓库名',
organizationName: '你的用户名',
\n\n

12.4 部署到其他平台​

\n

只要能把 build/ 目录的内容放到任意静态托管即可（Vercel、Netlify、自有 Nginx 等）。构建命令为 npm run build，站点根目录指向 build。

\n
\n

十三、常用命令速查​

\n
命令说明
npm run start启动开发服务器（可加 --host 0.0.0.0）
npm run build生产环境构建
npm run serve本地预览构建结果
npm run deploy构建并部署（如 GitHub Pages）
npm run clear清除缓存与构建产物
npm run swizzle <组件>将主题组件「拷贝」到项目以便覆盖
npm run write-translations生成多语言翻译文件
npm run docusaurus docs:version <版本号>为文档打版本
\n
\n

十四、学习路径小结​

\n
    \n
  1. 入门：创建项目 → 改 docs/intro.md → 看侧边栏与热更新
    2. \n
  2. 文档：在 docs/ 新增文档、用 Front Matter 和 _category_.json 组织侧边栏
    3. \n
  3. 内容：掌握 MDX、代码块、Admonition、自定义组件
    4. \n
  4. 博客：在 blog/ 写文章，配置 authors/tags
    5. \n
  5. 页面：在 src/pages/ 做关于页、落地页等
    6. \n
  6. 外观：改 custom.css、navbar、footer
    7. \n
  7. 配置：熟悉 docusaurus.config.ts 与 sidebars.ts
    8. \n
  8. 进阶：i18n、版本、Swizzle、自定义插件
    9. \n
\n

遇到问题可查阅 Docusaurus 官方文档。

", "url": "https://老王.me/blog/docusaurus-tutorial", "title": "Docusaurus 完整教程（新手向）", "summary": "由浅入深学习 Docusaurus，覆盖安装、文档、侧边栏、MDX、博客、页面、主题、配置与部署等主要知识点。", "date_modified": "2026-03-19T09:16:45.000Z", "tags": [] } ] }